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ACKNOWLEDGMENTS AND BACKGROUND 


Interlisp has evolved from a succession of LISP systems that began with a LISP designed and 
implemented for the DEC PDP-1 by D. G. Bobrow and D. L. Murphy! at Bolt, Beranek and 
Newman in 1966, and documented by D. G. Bobrow. An upwards compatible version of this LISP 
was implemented for the SDS 940 in 1967, by Bobrow and Murphy. This system contained the 
seeds for many of the capabilities and features of the current system: а compatible compiler and | 
interpreter,2 uniform error handling, an on-line LISP oriented editor? sophisticated debugging 
facilities,4 etc. 940 LISP was also the first LISP system to demonstrate the feasibility of using 
software paging techniques and a large virtual memory in conjunction with a list-processing system 
[8052]. DWIM, the Do-What-I-Mean error correction facility, was introduced into the system in 
1968 by W. Teitelman [Tei2], who was also responsible for documentation for the 940 LISP system. 


In 1970, an upwards compatible version of 940 LISP called BBN LISP? was designed for the PDP- 
10 by D. G. Bobrow, D. L. Murphy, A. K. Hartley, and W. Teitelman, and implemented by 
Hartley with assistance from Murphy. А. К. Hartley was also responsible for modifying the 940 
LISP compiler to generate code for the PDP-10. BBN-LISP ran under TENEX, a sophisticated 
time sharing system for the PDP-10 designed and implemented by D. С. Bobrow, J. D. Burchfiel, 
D. L. Murphy, T. R. Strollo, and R. S. Tomlinson.|[Bobl] With hardware paging and 256K of 
virtual memory provided by TENEX, it became practical to provide extensive and sophisticated 
interactive user support facilities, such as the programmer's assistant [Tei4], CLISP [Tei5], and а 
more sophisticated DWIM, all of which were designed and developed by W. Teitelman. In 1971, 
the block compiler was designed and implemented by D. G. Bobrow. In 1974, the ability to swap, 
i.e., overlay, compiled code was added, significantly increasing the virtual address space. In 1975, 
implementation of the spaghetti stack capability based on the Bobrow-Wegbreit model described іп 
[Bob3] was completed by А.К. Hartley. The BBN-LISP Manual [Tei3] was written by W. 


1 D. С. Bobrow is currently at Xerox Palo Alto Research Center (PARC), D. Г. Murphy is with Digital Equipment 


Corp. 

2 The preliminary version of the compiler was written by L. P. Deutsch, now at Xerox PARC. This was considerably 
modified and extended by D. L. Murphy before producing the final working version. 

3 The original idea of a LISP oriented structure editor belongs to L. P. Deutsch. The editor in its current form was. 
written by W. Teitelman, now of Xerox PARC. 

4 Designed and implemented by W. Teitelman. 

5 The design, construction and documentation for BBN LISP was sponsored by the Information Processing Techniques 


Section of the Advanced Rescarch Project Agency, as was all of the subscquent work on the system that was 
performed at BBN. Since March 1972, the contributions made to the development of the system by W. Teitelman, 
including the preparation of this manual, were sponsored by Xerox Palo Alto Rescarch Center. 
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Teitelman, with contributions from A. K. Hartley and from J. W. Goodwin, who also wrote 
TRANSOR and the special arithmetic functions, as well as a number of other utility functions. 
The name of the system was changed from BBN-LISP to Intcrlisp in 1973, when the maintenance 
and development of the system evolved into a joint effort between Bolt Beranek and Newman, and 
Xerox Palo Alto Research Center. The Interlisp reference manual was written by W. Teitelman, 
with contributions from (in alphabetic order) D. G. Bobrow, J. W. Goodwin, A. K. Hartley, P. C. 
Jackson, D. C. Lewis, and L. M. Masinter. The cover was designed by Alice R. Fikes. 


Interlisp-10 is currently the LISP system used at Bolt Beranek and Newman, Xerox Palo Alto 
Research Center, Stanford Research Institute Artificial Intelligence Center, Information Sciences 
Institute, the SUMEX facility at Stanford University, Yale University, Caltech, Rutgers, the 
University of Linkoping in Sweden and others. Interlisp-10 now runs under both the Tenex and 
TOPS-20 operating system, and is available through DECUS; the total Interlisp-10 user community 
. now comprises over three hundred users. То aid other Interlisp implementations and to encourage 
compatability between implementations, specifications of Interlisp can be found in "The Interlisp 
Virtual Machine Specification" [Moo]. | 


Interlisp is a continuously evolving system, both in response to complaints, suggestions, and 
requests of the many users scattered throughout the ARPA network, as well as the long range goals 
of the individuals primarily responsible for the system, waich are currently: | 


Person 

W. Teitelman - 
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Research Center 

3333 Coyote Hill Road 

Palo Alto, Calif. 94304 


A. K. Hartley 


Bolt Beranek & Newman - 


50 Moulton St. 
Cambridge, Mass. 02138 


D. C. Lewis 


Bolt Beranek & Newman . 


50 Moulton St. 
Cambridge, Mass. 02138 


L. M. Masinter 

Xerox Palo Alto 
Rescarch Center 

3333 Coyote Hill Road 

Palo Alto, Calif. 94304 


R. M. Kaplan 

Xerox Palo Alto 
Rescarch Center 

3333 Coyote Hill Road 

Palo Alto, Calif. 94304 


Responsible for 
User Facilities: i.e., pretty-print, editor, 
break and trace, advising, 


DWIM, CLISP, programmer's assistant, etc. 


Interlisp-10 interpreter, garbage collector, 
all SUBR's (hand-code machine language functions), 
compiler, spaghetti stack. 


Interlisp-10 input-output, readtables, 
terminal tables, user data types, overlays, TENEX 
functions. 


pattern match compiler, record package, 


MAST ERSCOPE. 


LISPUSERS packages 
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SECTION 1 
INTRODUCTION 


This document is a reference manual for Interlisp, a LISP system that is currently implemented on 
(or implementations are in progress for) at least five different machines. This manual is a reference 
manual for all Interlisp implementations, although it does contain some material that is relevant 
only to Interlisp-10, the implementation of Interlisp for the DEC PDP-10, models KA and KI, 
using the BBN TENEX time sharing system (Во51) апа Ше KL- 10 using the TOPS- 20 operating 
system.! Where this is the case, such material is clearly marked. 


Interlisp has been designed to be a good on-line interactive system (from which it derives its 
name). Some of the features provided include elaborate debugging facilities with tracing and 
conditional breakpoints (Section 15), and a sophisticated LISP oriented editor within the system 


(Section 9). Utilization of a uniform error processing through user accessible routines (Section 16) 


has allowed the implementation of DWIM, a Do-What-I-Mean facility, which automatically corrects 
many types of errors without losing the context of computation (Section 17). Тһе CLISP facility 
(Section 23) extends the LISP syntax by enabling ALGOL-like infix operators such as +, -, *, /, 
=, е, AND, OR, etc., as well as IF-THEN-ELSE statements and FOR-WHILE-DO statements. 
CLISP expressions are automatically converted to equivalent Interlisp forms when they are first 
encountered. CLISP also includes a sophisticated pattern match compiler, as well as a record 
package that facilitiates "data-less" programming. 


Interlisp has also been designed to be a flexible system. Advising (Section 19) enables users to 
selectively modify or short-circuit any system function. Even such "built-in" aspects of the system 
as interrupt characters, garbage collection allocation and messages, output radix, action on various 
error conditions, line-buffcring protocol, etc. all can be modified through system functions 
provided for that purpose. Readtables and terminal tables (Section 14) allow the user complete 
control over input, including the ability to define read macro characters, specify echo modes, even 
redefine the action of formatting characters such as parentheses. The user сап also define new 
datatypes (Section 23) in addition to the lists, strings, arrays, and hash association tables (hash 
links) already provided. 


А novel and изећ 1 facility of the Interlisp system 15 the programmer's assistant (Section 22), which 
monitors and records all user inputs. The user can instruct the programmer's assistant to repeat a 


Interlisp-10 is designed to provide the user access to the large virtual memory allowed by TENEX and TOPS-20, 
with relatively small penalty in speed (using special paging techniques described in [Bob2]). Interlisp-10 also provides 
for essentially unlimited quantity of compiled code via the overlay facility described in Section 3. Interlisp-10 was the 
first implementation of Interlisp, and is still the most widely used. 


11 


Section 1: Introduction 


particular operation or sequence of operations, with possible modifications, or to UNDO the effects 
of specified operations. The programmers assistant also includes a (limited) error analysis 
capability. The goal of the programmer’s assistant, DWIM, CLISP, etc. is to provide a 
programming environment which will "cooperate" with the user in the development of his 
programs, and free him to concentrate more fully on the conceptual difficulties and creative aspects 


of the problem he is trying to solve. 


Masterscope is an interactive program for analyzing user programs and determining what functions 
are called and by whom, how and where variables are bound, set, or referenced, which functions 
use particular record declarations, etc. It is extremely useful for building large systems. 


To aid in converting to Interlisp programs written in other LISP dialects, e.g., LISP 1.5, Stanford 
LISP, we have implemented TRANSOR, a subsystem which accepts transformations (or can 
operate from previously defined transformations), and applies these transformations to source 
programs written in another LISP dialect, producing object programs which will run on Interlisp 
(Appendix 1). Іп addition, TRANSOR alerts the programmer to problem areas that (may) need 


. further attention. TRANSOR was used extensively in converting from 940 LISP to DBN-LISP on 


the PDP-10. A set of transformations is available for converting from Stanford LISP and LISP 1.5 
to Interlisp. | | 


A complete format directed list processing system FLIP [Teil], is available for use within Interlisp. 
The TXDT package [Moo2] provides a powerful set of text editing primitives implemented in 
Interlisp from which the user can easily construct and experiment with a variety of editors. 
HELPSYS, an on-line information retrieval package that uses this manual as a data-base is also 
available to provide the user with immediate access to documentation. 


Although we have tried to be as clear and complete as possible, this document is not designed to 
be an introduction to LISP. Therefore, some parts may only be clear to people who have had 


some experience with other LISP systems. A good introduction to LISP has been written by Clark - 


Weissman [Weil] Although not completely accurate with respect to Interlisp, the differences are | 


small enough to be mastered by use of this manual and on-line interaction. Another useful 


introduction is given by Berkeley [Berl] in the collection of Berkeley and Bobrow [Ber2]. 
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First revision, October, 1974. 


The first revision of the Interlisp Reference Manual corresponds to changes or additions to the 
Interlisp system during the first ten months of 1974. Approximately 200 (out of 700) pages have 
been changed to some extent in this revision. A significant number of these (about 60 pages) 
occur in Section 14 (input/output). About 30 pages of chapter 23 (CLISP) have been changed, 
and the rest of the changes are scattered throughout the manual. Changed material in the text is 
flagged in the outside margin by the appearance of either a "+" (for addition of completely new 
material), "-" (for deletion of original material), ог "*" (indicating changes to existing material that 
more or less preserve its original structure.) Thus the reader who is already familiar with the 
Interlisp manual can quickly determine what has been changed. Note: very few of these changes 
are not "upwards compatible" with the original manual, i.e., almost all of them represent extensions 
or additions. Nevertheless, the reader is encouraged to skim through the manual noting changes 
which may affect him. | 


Second revision, November, 1975. 


The second revision of the Interlisp Reference Manual corresponds to changes or additions to 
Interlisp from October, 1974 to November, 1975; the most important change is the introduction of · 
the spaghetti stack capability, Section 12. As before, material in the text is flagged in the outside | 
margin by the appearance of either a "+", "“", ог "- 


Third revision, October, 1978. 


The third revision of the Interlisp Reference Manual corresponds to changes or additions to 
Interlisp from November, 1975 to October, 1978. As before, new material is flagged with a "+" 
іп the margin, changed material а "*". The most important change is the switch from a deep 
binding scheme to shallow binding (Section 12), with a significant improvement in performance of 
interpreted and non-block compiled programs. 


In addition, this new manual includes a number of packages and tools developed and then proven 
in actual use over the last several years by the user communitics at PARC and BBN. Some of 
these are now included as part of the standard system, and are documented in the appropriate 
places in the manual, such as the font package for producing listings with multiple fonts (Section 
14); the editdate package for time stamping changes to functions plus many new and powerful edit 
commands (Section 9); an improved and generalized file package (Section 14); the printout package 
which permits thc user to specify in a single succinct expression, large variety of fancy printing 
controls, c.g. various flavors of prints, prettyprints, special number formatting, paragraph printing, 
centering, right justifying (Section 23); the Pmap facility which allows paged access to files in 
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Interlisp-10 (Section 21), екс. Others are not a part of the system (in the interest of space) but are | 


available as loadable files. These are documented in Section 24, Lispusers Packages, and include: а 
hash package used for maintaining large symbolic databases on files, which permits information to 
be associated with an atom or string and quickly returned; the Decl package which extends 
Interlisp to allow declaration of the types of variables and expressions appearing in functions; the 


Exec package which provides a number of TENEX/TOPS-20 capabilities to Interlisp programs 
directly; the Ftp package which makes it possible to deal with files at оше hosts on the- VNDE 
network as if they were files on the user's local machine; etc. 


The last three years have seen E rapid growth in the Interlisp community, especially since the | 
availability of Interlisp оп the TOPS-20 operating system. As of this writing, Interlisp-10 is in use 


8t 13 computer centers on 1 23 different computers, 11 of them KL-10’s running TOPS-20. 
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$ЕСТ!ОМ 2 
USING INTERLISP 


2.1 USING THE INTERLISP MANUAL - FORMAT, NOTATION, AND 
CONVENTIONS 


The Interlisp manual is divided into separate, more or less independent sections. Each section is 
paginated independently, to facilitate issuing updates of sections. Each section contains an index to 
key words, functions, and variables contained in that section. In addition, there is a composite 
index for the entire manual, plus several appendices and a table of contents. - 


Interlisp is currently implemented on (or implementations are in progress for) at least four different 
computers. This manual purports to be a reference manual for all implementations of Interlisp, 


both present and future. However, since the largest user community is still that of Interlisp-10, the 


implementation for the DEC PDP-10 series! the manual does contain some implementation 
dependent material. Where this is the case, the text refers to Interlisp-10, and is indicated as such. 


Throughout the manual, terminology and conventions will be offset from the text and typed in 
italics, frequently at the beginning of a section. For example, one such notational convention is: 


The names of functions and variables are written in lower case and underlined when they appear 


in the text. Meta-LISP notation is used for describing forms. 


Examples: member[x;y] is equivalent to (MEMBER X Y), member{car[x];FOO] is equivalent to 
(MEMBER (CAR X) (QUOTE F00)). Note that in meta-LISP notation lower case variables аге 
evaluated, upper case quoted. 


. notation is used to distinguish between cons and list. 


eg. Ех=(А B С), (РОО x) is (FOO (A В C)), whereas (FOO.x) is (FOO A B C). In 
other words, x is cadr of (FOO x) but cdr of (FOO . x). Similarly, y is caddr of (FOO x y), but cddr 


of (РОО х. у). Note that this convention is in fact followed by the read. program, 


i.c., (FOO . (A B C)) and (FOO A B C) read in as cqual structures. 


includes the KA and KI versions of the PDP-10 running the TENEX operating system, and the KL-10 or DEC 2020 
running the TOPS-20 operating system. 
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Other important conventions are: 
TRUE in Interlisp means not NIL. 


The purpose of this is to allow a single function to be used both for the computation of some 
quantity, and as а test Юг a condition. For example, the value of member[x;y] is either NIL, or 
the tail of y beginning with x. Similarly, the value of or is the value of its first TRUE, i.e., non- 
. NIL, expression, and the value of and is cither NIL, or the value of its last expression. 


Although most lists terminate in NIL, the occasional list that ends in an atom, e.g. (A B . C) or 
worse, a number or string, could cause bizarre effects. Accordingly, we have made the following 
implementation decision: 


All functions that iterate through а list, e.g, member, length, тарс, etc. terminate by an nlistp | 
check, rather than the conventional null-check, as a safety precaution against encountering data 
types which might cause infinite cdr loops, e.g., strings, numbers arrays. | 


Thus, 


member[x:(A В . C)] = member[x:(A B)] 
revers[((A В . C)] = reverse[(A B)] | 
append[((A В . С);у] = append[(A B);y] 


For users with an application requiring extreme efficiency? we have provided fast versions of 
memb, last, nth, assoc, and length which compile open and terminate on NIL checks, and therefore 
may causc infinite cdr loops if given poorly formed arguments. However, to help detect these 
situations, fmemb, flast, fnth, fassoc, and flength all generate errors when interpreted if their 
argument ends in a non-list other than NIL, e.g. BAD ARGUMENT - FLAST. _ 


Most functions that set system parameters, e.g. printlevel, linelength, radix, etc, return as their 
value the old setting. If given NIL as an argument, they return the ‹ current value шош 
changing it. 


All SUBRS, ie, hand coded functions, such as read, print, eval, cons, etc, have "argument 
names" selected from U, V, W, X, Y, 7, as described under arglist, Section 8. However, for 
tutorial purposes, more suggestive names are used in the descriptions of these functions in the text. 


Most functions whose names end in p are predicates, e.g., numberp, tailp, exprp; most n" 
whose names end in а are nlambda's, ie, do not require quoting their е e.g., setq, 
defineq, nlsetq. | 


X is equal to y" means equal[x:y] is true, as opposed to "x is eq to y" meaning ед/х; y is ыы 
ге, x and у are the same identical LISP pointer. 


Ға 


А NIL check can be executed in only one instruction, an nlistp on Interlisp-10 requires about 8, ашы ad both 
generate only one word of code. | 
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When new literal atoms are created (by the read program, pack, or mkatom), they are provided 
with a function definition cell initialized to NIL (Section 8), and a property list initialized to NIL 
(Section 7). The function definition cell is accessed by the functions getd and рша described in 
Section 8, and the property list by the functions getproplist and setproplist, (Section 7). 


car of NIL and cdr of NIL are always NIL, and the system will resist attempts to change them. _ 


Neither NIL nor T can be used as bound variables, ie. used as the names of arguments in a 
lambda expression, or as a prog variable. | 


The term list refers to any structure created by one or more conses, i.e, it does not have to end іп 
NIL. For example, (A . B) is a list. The function listp, Section 5, is used to test for lists. 
Note that not being a list does not necessarily imply an atom, e.g., strings and arrays are not lists, 
nor are they atoms. See Section 10. 


Many system functions have extra optional arguments for internal use that are not described in the 
writeups. For example, readline is described as a function of one argument, but 
arglisti[( READLINE] is (RDTBL LINE LISPXFLG). These arguments are indicated in the 
manual by the appearance of "-" 
should just ignore the extra arguments. 


Interlisp departs from LISP 1.5 and other LISP dialects in that car of a form is never evaluated. In 
other words, if car of a form is not an atom with a function definition, and not a function object, 
ie. а list car of which is LAMBDA, NLAMBDA, or FUNARG, an error is generated. apply ог 
apply* (Section 8) must be used if the name of a function is to be computed as, for example, when 
functional arguments are applied. 


2.2 USING THE INTERLISP SYSTEM - AN OVERVIEW 


Call Interlisp by typing LISP followed by a carriage return. Interlisp will type an identifying 
message, the date, and а grecting, followed by а "е". 
изег is "talking to" the top level Interlisp exccutive, called evalqt, (for historical reasons), just as 
"(а)" indicates the user is talking to the operating system. evalqt calls lispx which accepts inputs in 
either eval or apply format: if just one expression is typed on a line, it is evaluated; if two 
expressions are typed, the first is apply-cd to the second. eval and apply are described in Section 
8. In both cases, the value is typed, followed by + indicating Interlisp is ready for another input. 


Interlisp is normally exited via the function logout, i.e., the user types LOGOUT( ). However, 
typing control-C at any point in the computation returns control immediately to the operating 
system. The user can then continue his program with no ill effects with the CONTINUE command, 
even if he interrupted it during a garbage collection.? Typing control-D at any point during a 


computation will return control to evalqt. If typed during a garbage collection, the garbage 


collection will first be completed, and then control will be returned to Interlisp's top level; 
otherwise, control rcturns immediately. 


Typing START will attempt to re-enter Interlisp at top level evalqt. However, there are many situations where this 


might Ісауе the system in an inconsistent state. Thus control-C START is быу not adviscable unless no other 
recourse is available (e.g. user accidentally turns all interrupts off). | 
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in the arglist, eg. readlinefrdtbl;-;-]. In such cases, the user 


This prompt character indicates that Ше 


++ 


++ 


+++ 
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When typing to the Interlisp 1 read program, typing a control- Q4 will cause Interlisp to print "# #" 
and clear the line buffer, i.e., erase the entire line up to the last carriage return. Typing control-A? 
erases the last character typed in, echoing a \ and the erased character. Control-A will not back up 
beyond the last carriage return. Typing control-W within a call to read or readline will erase the 
last expression typed, echoing a ХХ. Control-W will back up to previous lines. Control-O сап be 
used to immediately clear the output buffer, and <del> to immediately clear the input buffer.Ü In 
addition, typing control-U^ will cause the Interlisp editor (Section 9) to be called on the expression 
being read, when the read is completed. Appendix 1 contains a list of all control characters, and a 
reference to that part of the manual where they are described. Section 16 describes how the 
system's interrupt characters can be disabled or redcfined, as well as how the user can define his 
own interrupt characters. | | 


Since the Interlisp read program is normally line-buffered to make possible the action of 
control-Q,? the user must type a carriage return before any characters arc delivered to the function 
| requesting input, е.2., 


СЕ Тә 9 
| 


However, the read program automatically supplies. (and prints) this carriage return when a 
matching right parenthesis is typed, making it unnecessary for the user to do so, e.g., 


-CONS(A B) | 
(А.В) 


Тһе Interlisp read program treats square brackets as "super-parentheses": a right square bracket 
automatically supplies enough right parentheses to match back to the last left square bracket (in the 
expression being read), or if none has appeared, to match the first left parentheses, е.р., | 


(А (B (С]=(А (В (C))). 
(А [В (С (0) E)-(A (B (C (0))) Е). 


% is the universal escape character for read. Thus to input an atom containing a syntactic 
delimiter, precede it by %, e.g., АВ% (С or %%. See Section 14 for more details. 


tV (control-V) can be used to type a control character that would otherwise interrupt the input 


process, e.g., control-D, control-C, etc. If the character following ТУ is A, В, .. or 2, the 
corresponding control character is input, е.р., ТУАТУВТУС is the atom control-Acontrol-Bcontrol-C. 


+ 4 control-U for Interlisp-10 оп TOPS-20. 

+ 5 del? for Interlisp-10 on TOPS-20. 

The action of control-Q takes place when it is read. If the user has "typed ahead" several inputs, control-Q will only - 
affect at most the last line of input. < del > (control-Z on TOPS-20). however, is an interrupt character that will clear 
the entire input buffer as soon as it is typed, 1.е., even during a garbage collection. 

+ 1 control-N for Interlisp-10 on TOPS-20. 


Except following control[T], sce Section 14. 


"2" is used throughout the manual to denote carriage-return. 
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tV followed by any other character has no effect, i.c.. ЕООТУЈ and FOOL are identical. For more 
details, see Appendix 1. 


| Typing ' immediately in front of any expression has the effect of quoting the expression, i.e., 
(A 'B C) is read as (А (QUOTE B) C). See Section 14. 


At any point during input, the user can type ?— followed by carriage-return and be given the 
argument names and corresponding values (if any) of the expression (form) being typed. Typing 
just ? carriage-return will cause the user to reccive information from the Interlisp manual about the 
expression or command being typed. In the following example underlined characters were typed 
by the user. 


-(SETQ FOO (ELT 3 ?=2 
А = 3 
М 


(ELT 3 22 


elt[a;n] Value is nth element of the array a. 
| elt generates an error, ARG NOT ARRAY, 
if a is not the beginning of an array. 


(ELT З TW\\3 A 3] 


? is also a programmer assistant command for use following an error. In many cases, the 
programmer's assistant can analyze the cause of the error (see example below) If not, the 
programmer's assistant simply presents information about the error from the manual. 


EXAMPLE 


Most of the "basics" of on-line use of Interlisp, e.g., defining functions, error handling, editing, 
saving your work, etc., are illustrated in the following brief console session. Underlined characters 
werc typed by the user. 


1. Тһе user calls Interlisp from the operating system, in this case Tenex, Interlisp prints a date, 
and a grecting. The prompt character e indicates the user is at the top level of Interlisp. 


2. Тһе user defines a function, fact, for computing factorial of n. In Interlisp, functions are 
defined via DEFINE or DEFINEQ, (Section 8). Functions may independently evaluate | 
arguments, or not evaluate them, and spread their arguments, or not spread them (Section 4). 
The function fact shown here is an example of an everyday run-of-the-mill function of one 
argument, which is evaluated. The function definition uses CLISP (Conversational LISP, 
section 23). The CLISP will automatically be converted to LISP when the function is run. 


3. The user "looks" at the function definition. Function definitions in Interlisp are stored in a 
special cell called the function definition cell, which is associated with the name of the 
function (Section 8). This cell is accessible via the two functions, дес and рша, (define and 
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defineq use рша). Note that the user typed an input consisting of a single expression, i.e., 


(СЕТО (QUOTE FACT)), which was therefore interpreted as à form for eval. The user 


could also have ty ped GETD(F АСТ). 


The user runs his function. Two errors occur and corrections are offered by DWIM (Section 


17). In each case, the user indicates his approval, DWIM makes the correction, i.e., actually 


changes the definition of fact, and then continues the computation. 


An error occurs that DWIM cannot handle, and the system goes into a break. At this point, 
the user can type in expressions to be eval-ed or apply-ed exactly as at the top level. ‘The 
prompt character ":" 


to itimes in which the error occurred. 


The user types in the break command, BT, which calls for a backtrace to be printed. In 
Interlisp, interpreted and compiled code (see Section 18 for discussion of the compiler) are 


- completely compatible, and in both cases, the name of the function that was called, as well as 


and/or modified in various ways (see Section 12). 


Break commands are discussed in Section 15, which also explains how the user can "break" a 
particular function, i.e., specify that the system go into a "break" whenever a certain function 
or functions are called. At that point the user can examine the state of the pu”: 
This facility is very useful for debugging. 


indicates that the user is іп a break, іе, that the context of his 
computation is available. In other words, the system is actually "within" or "below" the call- 


the names and values of its arguments are stored on the stack. The stack can be searched | | 


The user asks for the value of the variable n, i.e., the most recent value, or binding. The 


interpreter will search the stack for the most recent binding, and failing to find one, will 


obtain the top level value from the atom’s value cell, which is car of the atom (Section 3). ЈЕ 


there are no bindings, and the value cell contains the atom NOBIND, an unbound atom error . 


is са (беспоп 16). 


The user pe ?. a command to the programmer's assistant (Section 22). The p.a. looks at | 


the error and the context and using its information about ITIMES, "explains" the error. 


'The user realizes his error, and calls the editor to fix it. (Note that the system is still in the 


P Huy of ешр; Section 9 begins with a simple introduction designed for the new user. 


| 10. 


The user instructs the editor to replace all NIL’s (in this case there is only onc) by. 1. The 


editor physically changes the expression it is operating оп 50 when the user exits from the 


editor, his function, аз И is now being interpreted, has been changed. 
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@LISP.2 


INTERLISP-10 14-JUL-78 ... 


Good Evening. 
-DEFINE FACT (LAMBDDA (N) (ТЕ N=0 THEN NIL ELSE N*(FACTT N-1 
(FACT) ` | 


С(СЕТО 'FACT) 
(LAMBDDA (М) (IF N=0 THEN NIL ELSE N*(FACTT N- 9) 


«ҒАСТ(3). 
LAMBDDA {below FACT} -> LAMBDA ? Yes 
FACTT {in FACT} -> FACT ? Yes 


NON-NUMERIC ARG 
NIL 
IN ITIMES 


(broken) 


because ITIMES requires that each of its arguments be a number 
but in (ITIMES М (FACT (5081 N))) (IN FACT}, 
the value of (FACT (SUB1 N)) is NIL when М=1 


: EDITF( FACT) 
EDIT | 


“(В NIL 1) 
*0K2 

FACT 

: RETURN 12 
'BREAK' = 1 


6 
«РР FACT? 


(FACT 
[LAMBDA (N) 
( COND 
((ТЕВОР 0) 


(T (ITIMES N (FACT (SUB1 му) 

ҒАСТ 
«MAKEFILES() 
****NOTE: Тһе following are not contained on any file: 

the functions: FACT 
want to say where they go? Yes 
(functions) 
FACT File Мате: FACT} 

new file? Yes 
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de PACT ii 
+ (<TEITELMAN>FACT. ; 1) 
+ eLOGOUT( ) 
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The user exits from the editor and returns to the break. 


The user specifies the value to be used by itimes in place of NIL by using the break 
command RETURN. This causes the computation to continue, and 6 is ultimately returned as 
the value of the original input, fact(3). 


The user prettyprints (Section 14) fact, i.e., asks it be printed with appropriate indentations to 
indicate structure. Prettyprint also provides a comment facility. Note that both the changes 
made to fact by the editor and those made by DWIM are in evidence. 


\ 


The user calls makefiles (Section 14) to write out any changes he has made. The file package 
knows that the function fact has been changed, but doesn’t know on which file it belongs, and 
asks the user as shown in the example. After this interaction, the symbolic file 
<TEILITELMAN>FACT. ;1 is written out. This file can be loaded into Interlisp at a later date 
via the function load (Section 14), will cause fact to be defined as it currently is. There is also 
a facility in Interlisp for saving and restoring an entire core image via the functions sysout 
and sysin (Section 14). | 


The user logs out, returning control to Tenex. However, һе сап still continue his session by 
re-entering Interlisp via the Tenex CONTINUE command. 
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ЈАС ЕХ Es бин” РТ ии вор аа ТСС СЕ 
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FEENGTHEXT ооа рег: Аа Ы БЕ ТСТ 
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SECTION 3 


DATA TYPES, STORAGE ALLOCATION 
GARBAGE COLLECTION, AND OVERLAYS 


Interlisp operates іп an 18-bit address space. This address space is divided into 512 word pages 
with a limit of 512 pages, or 262,144 words, but only that portion of address space currently in use 
actually exists on any storage medium. Interlisp itself and all data storage are contained within this 
address space. A pointer to a data element such as a number, atom, etc., is simply the address of 
the data element in this 18-bit address space. | 


3.1 БАТА ТҮРЕ5 


The data-types of Interlisp are lists, atoms, pnames, value cells, arrays, large and small integers, 
floating point numbers, stack pointers, string characters and string pointers. There is also a way to 
define new data-types described below in section 3.2. Compiled code, read tables, terminal tables, 
and hash arrays are currently included with arrays. 


In the descriptions of the various data-types given below, for each data type, first the input syntax 
and output format are described, that is, what input sequence will cause the Interlisp read program. 
to construct an element of that type, and how the Interlisp print program will print such an 
element. Next, those functions that construct elements of that data-type are given. Note that some 
data-types cannot be input, they can only be constructed, e.g. arrays. Finally, the format in which 
an element of that data-type is stored in memory is described. 


3.1.1 LITERAL ATOMS 

А literal atom is input as any string of non-delimiting characters that cannot be interpreted as а 
number. The syntatic characters that delimit atoms called separator or break characters (Section 
14) and normally are space, end-of-line,? line-feed, % ( ) " | and |. However, these characters may 


Бс included in atoms by preceding them with the escape character 90. 


Literal atoms are printed by print and prin2 as a sequence of characters with %’s inserted before all 


1 Interlisp is currently implemented on (or implementations are in progress for) at least four different machines. This 
section treats subjects that are for thc most part somewhat implementation dependent. Where this is the case, the 
discussion refers to Interlisp-10, the implementation for the DEC PDP-10, on which Interlisp was first implemented. 
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Ап end-of-line character is transmitted by ТЕМЕХ when it sees а carriage-return. 
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delimiting characters (so that the atom will read back in properly). Literal atoms are printed by 


prinl as a sequence of characters without these extra %’s. For example, the atom consisting of the- 


five characters A, B, C, (, and D will be printed as ABC%(D by print and ABC(D by prinl. 
The extra %’s are an artifact of the print program; they are not stored in the atom’s pname. 


Literal atoms can be constructed by pack, mkatom, and gensym (which uses mkatom). 


Literal atoms are unique. In other words, if two literal atoms have the same pname, i.e. print the 
same, they will always be the same identical atom, that is, they will always have the same address 
in memory, or equivalently, they will always be eq. Thus if pack or mkatom is given a list of 
characters corresponding to a literal atom that already exists, they return a pointer to that atom, 
and do not make a new atom. Similarly, if the read program is given as input of a реке of 
characters for which an atom already exists, it returns a pointer to that atom. | 


A literal atom is а datum consisting of the following components: a property list, initially NIL, 
(accessed by getproplist and setproplist, Section 7), a value, (accessed by getatomval and setatomval, 


Section 5), a function definition, initially NIL, (accessed by getd and putd, Section 8), and a 


pname, (not directly accessible). 


3.1.2 PNAMES 


The pnames of atoms^ comprise another data-type with storage assigned as it is needed. This 


data-type only occurs as a component of an atom or a ae It does not appear, for example, as 
an element of a list. 


Pnames have no input syntax or output format as iey cannot be directly кшш бу ace 
programs. 


A pname is a sequence of 7 bit characters packed 5 to a word, beginning at a word boundary. The 


first character of a pname contains its length; thus the maximum length of a рше is 126 
characters. | 


3.1.3 VALUE CELLS 


“Тһе value cells of atoms comprise another data-type with storage assigned as it is needed. Value 


cells occur only as part of an atom. If an atom is ever referenced as a variable, either by setq, or - 


by use as the argument of a function, or bound as a prog variable, a value cell is created and 


assigned to the atom. The value cell will then always contain the current value of the atom. Note- 


that from the standpoint of a function that references the value of an atom, an atom having no 


Note that this is лог true for strings, large integers, floating point numbers, and lists, i.e. they all can print the same 
without being eq. 


__ АП Interlisp pointers have pnames, since we define a pname simply to be how that pointer is printed. However, only 
literal atoms and strings have their pnames explicitly stored. Thus, the use of the term pname in a discussion of 

. data-types or storage allocation means pnames of atoms or аши. and refers to а sequence of ares stored in а 
certain part of Interlisp’s memory. 
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= Data Туре$ 


value cell is indistinguishable from an atom whose value cell contains the atom NOBIND.> 


Value cells have no input syntax or output format as they cannot be directly referenced by user 
programs. 


3.1.4 NUMERICAL ATOMS 


Numerical atoms, or simply numbers, do not have property lists, value cells, functions definition 
cells, or explicit pnames. There are currently two types of numbers in Interlisp: integers, and 
floating point numbers. 


INTEGERS 


The input syntax for an integer is an optional sign (+ or -) followed by a sequence of digits, 
followed by an optional Q. 6 If the О is present, the digits are interpreted in octal, otherwise іп 
decimal, e. g. TIQ and 63 both correspond to the same integers, and in fact are indistinguishable 
internally since no record is kept of how integers were created. 


The setting of radix (Section 14), determines how integers are printed: signed or unsigned, octal or 
decimal. 


Integers are created by pack and mkatom when given a sequence of characters observing the above 
syntax, e.g. (PACK (LIST 1 2 (QUOTE 0))) = 10. Integers are also created as а result of 
arithmetic operations, as described in Section 13. | | 


An integer is stored in опе 36 БИ word; thus its magnitude must be less than 2135.’ To avoid 
having to store (and hence garbage collect) the values of small integers, a few pages of address 
space, overlapping the Interlisp-10 machine language code, are reserved for their representation. 
The small number pointer itself, minus a constant, is the value of the number. Currently the range 
of "small" integers is -1536 thru +1535. The predicate smallp is used to test whether an integer is 
"small" 


While small integers have a unique representation, large integers do not. In other words, two large 
integers may have the same value, but not the same address in memory, and therefore not be eq. 
For this reason the function iegp (or equal) should be used to test equality of large integers. 


5 The latter case can occur for example if the user types SET(FOO exp), then undocs (Section 22) the set operation, 
thereby restoring the atom to its original "value", 

6 and terminated by a delimiting character. Note that some data-types are self-delimiting, e.g. lists. 
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If the sequence of digits used to create the integer is too large, the high order portion is discarded. (The handling of 
overflow as a result of arithmetic opcrations is discussed in Section 13.) 


33 
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FLOATING POINT NUMBERS 


A floating point number is input as a signed integer, followed by a decimal point, followed Әу. 
another sequence of digits called the fraction, followed by an exponent (represented by E followed. 
by a signed integer).8 Both signs are optional, and cither the fraction following the decimal point, 
or the integer preceding the decimal point may be omitted. Опе or the other of the decimal point | 


ог exponent may also be omitted, but at least one of them must be present to distinguish a floating 
point number from an integer. For example, the following will be recognized as floating point 


numbers: 


5. 500 5.01 3 5Е2 51Е2 | 
5Е-3 -52Е+6 | 


Floating point numbers are printed using the facilities provided бу ТЕМЕХ. Interlisp-10 calls the 
floating point number to string conversion routines’ using the format control specified by the 
function fltfmt (Section 14). 10 fltfmt is initialized to T, or free format. For campis the above 
floating point oint numbers would be e printed free format as: 


50. 250 5.01 3 5000... 5100 
| 005 -5 286 | 


Floating point numbers are also created by pack and mkatom, and as a result of arithmetic 
operations as described in Section 13. 


“А floating point number is stored in one 36 bit word in standard PDP-10 format. The range is 


++ 


+2.94E-39 thru +1.69E38 (or 21-128 thru 21127). 


3.1.5 LISTS 


The input syntax for a list is a sequence (at least one)!! of Interlisp data elements, e.g. literal atoms 
numbers, other lists, etc. enclosed in parentheses or brackets. A bracket can be used to terminate 
several lists, e.g. (A (B (с1. as described in Section 2. 


If there are two or more тени in a list, the final clement сап be preceded by a . (delimited on © 
both sides), indicating that cdr of the final node in the list is to be the element immediately 
following the „ер. (А . В) or (AB C . D), otherwise cdr of the last node in a list will be 
NIL. Note that the input sequence (A B C . NIL) is thus 15 equivalent to (A В С), and that 
(АВ. (С D)) is thus equivalent to (АВ С 0). Note however that (A В. СО) will 
create a list containing the five literal atoms А В . С and 0. 


8 and terminated by a delimiter. 
9 Additional information concerning these conversions тау be obtained from the TENEX JSYS Manual, 
00 The printnum package (Section 14) permits greater controls on the printed appearance of floating point numbers, 
allowing such things as left-justification, suppression of trailing decimals, etc. | 
11 О is read as the atom NIL. 
12 


Note that in Interlisp terminology, а list does not have to end in NIL, it is simply a structure composed of one ог 
more conses. | 


3.4 


Data Types 


Lists are constructed by the primitive functions cons and list. 


Lists are printed by printing a left parenthesis, and then printing the first element of the 115113 
then printing a space, then printing the second element, etc. until the final node is reached. Lists 
are considered to terminate when cdr of some node is not a list. If cdr of this terminal node is 
NIL (the usual case), car of the terminal node is printed followed by a right parenthesis. If cdr of 
the terminal node is not NIL, car of the terminal node is printed, followed by a space, a period, 
another space, cdr of the terminal node, and then the right parenthesis. Note that a list input as 
(AB С. NIL) will print as (A B C), and a list input as (A B . (C D)) will print as 
(A B C D). Note also that printlevel affects the printing of lists to teletype, and that carriage 
returns may be inserted where dictated by linelength, as described in Section 14. 


A list is stored as a chain of list nodes. A list node is stored in one 36 bit word, the right half 
containing car of the list (a pointer to the first element of the list), and the left half containing cdr 
of the list (a pointer to the next node of the list). 


3.1.6 ARRAYS 


An array in Interlisp is a one dimensional block of contiguous storage of arbitrary length: Arrays 
do not have input syntax; they can only be created by the function array. Arrays are printed by 
both print, prin2, and prinl, as # followed by the address of the array pointer (in octal). Array 
elements can be referenced by the functions elt and eltd, and set by the functions seta and setd, as 
described in Section 10. 


Arrays are partitioned into four sections: a header, a section containing unboxed numbers, a section 
containing Interlisp pointers, and a section containing relocation information. The last three 
sections can each be of arbitrary length (including 0); the header is two words long and contains 
the length of the other sections as indicated in the diagram below. The unboxed number region of 
an array is used to store 36 bit quantities that are not Interlisp pointers, and therefore not to be 
chased from during garbage collections, e.g. machine instructions. The relocation informaion is 
used when the array contains the definition of a compiled function, and specifies which locations in 
the unboxed region of the array must be changed if the array is moved during a garbage collection. 


The format of an array in Interlisp-10 is as follows: 


13 The individual clements of a are printed using prin2 if the list is being printed by print or prin2, and by prinl if 


the list is being printed by prin nl. 
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ADDRESS OF RELOCATION | 
INFORMATION — LENGTH | 

| USED BY GARBAGE ADDRESS OF POINTERS 
| 7 COLLECTOR ша 


HEADER WORD О 


WORD | 


FIRST DATA WORD 
NON-POINTERS 


POINTERS | 
| RELOCATION ра 
INFORMATION 
FIGURE 3-1 
The header contains: 
word 0 right | - length of entire Моск-- ARRAYSIZE +2. 
left — | - address of relocation information relative to word 0 of block (> 0 if 


relocation information exists, negative if array is a hash array, 0 if. 
ordinary array). 


word 1 right - address of pointers relative to word 0 of block. 


left z- used by garbage collector. 


3.1.7 STRINGS 


The input syntax for а string is a ", followed by a sequence of any characters except " and %, 
terminated by a "." and % may be included in a string by preceding them with the escape 
character 96. | | ШЕ 


Strings are printed by print and prin2 with initial and final "5, and 975 inserted where necessary 
for it to read back in properly. Strings are printed by prinl without the delimiting "5 and extra 
%’s. 


. Strings are created by mkstring, substring, and concat. | 
. Internally a string is stored in (мо parts; a string pointer and the sequence of characters. The 


Interlisp pointer to a string is the address of the string pointer. The string pointer, in turn, 
contains Ше character position at which Ше string characters begin, and the number of characters. 


3.6 


Data Types 


String pointers and string characters are two separate data-types,!^ and several string pointers may 
reference the same characters. ‘This method of storing strings permits the creation of a substring 
by creating a new string pointer, thus avoiding copying of the characters. For more details, see 
Section 10. 


String characters are 7 bit bytes packed 5 to a word. The format of a string pointer 15: 


Ж OF CHARACTERS | 5 * ADDRESS OF STRING + CHARACTER 
POSITION 


0 4 15 | 35 
FIGURE 3-2 


The maximum length of a string is 32K (K = 1024) characters. 


3.2 USER DEFINED DATA TYPES» 


In addition to the several built-in data-types such as atoms, lists, arrays, etc., Interlisp provides a 
way of defining completely new classes of objects, with a fixed number of fields determined by the 
definition of the data-type. Facilities are provided for declaring the number and type of the fields 
for a given class, creating objects of a given class, accessing and replacing the contents of each of 
the fields of such an object, as well as interrogating such objects. 


In order to define a new class of objects, the user must supply a name for the new data-type and 
specifications for each of its fields. Each field may contain either a pointer (ie, any arbitrary 
Interlisp datum), an integer, a floating point number, or an n-bit integer. 


The above operations are accomplished via the function declaredatatype. 


declaredatatype[typename;fieldspecs;-] 
typename is a literal atom, which specifies the name of the 
data-type. ficldspecs is a list of field specifications. Each field 
specification may be one of the following: ! 


POINTER ficld may contain any Interlisp datum 
FIXP field contains an integer 


14 String characters are not directly accessible by user programs. 


15 


The most convenient way to define new data-types is via DATATYPE declarations іп the RECORD package (as 
described in Section 23). 
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fetch ficld[descriptor;datum] 


FLOATP. | field contains a floating point number 
(BITS n) | field contains a non-negative integer less 
| than 27, 


declaredatatype returns a list of field descriptors, one for each 
element of  fieldspecs. Тһе field 
descriptor contains information about 
where within the datum the field is 
actually stored. ІҒ typename is already 
declared a datatype, it is re-declared. If 
ficldspecs is NIL, typename is 
"undeclared". 


Returns the contents of the ficld described by descriptor from 


datum. descriptor must be a "Пеја descriptor" as returned by 


declaredatatype. If datum is not an instance of the datatype of 


which descriptor is a descriptor, causes error 


DATUM ОҒ INCORRECT ТҮРЕ. 


replacefield[descriptor;datum; МЕЗЕ 


ncreate[typename; тот] 


getfieldspecs[typename] 


-getdescriptors[typename] 
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Store newvalue into the field of datum: described by descriptor. 
descriptor must be а field descriptor, as returned by 
declaredatatype. If datum is not an instance of the datatype of 
which descriptor 15 а descriptor, causes error 
DATUM OF INCORRECT TYPE. Value is newvalue. | 


creates and returns a new instance of datatype typename. 


If from is also a datum of datatype typename, the fields of the new | 


object are initialized to the values of the лш, fields in 
from. 


If typename is not the type name of a previously declared user!’ 
data type, generates an error, ILLEGAL DATA TYPE. 


Returns a list which is equal to the fieldspecs argument given to 


declaredatatype for typename; if typename is not a currently | 


declared data-type, returns NIL. 


Returns a list of бе descriptors, equal to the value of 
declaredatatype for typename. | g 


сте: ncreate will not work for built in datatypes, such as АККАУР, STRINGP, etc. 


3.8 


User Defined Data Types 


userdatatypes|] Returns list of names of currently declared user datatypes. 


In Interlisp-10, user datatypes are allocated starting with type number 31. The minimum amount 
of space that can be assigned to any one data-type is one page, thus effectively limiting the number 
of possible data types. The fields are rearranged internally so that pointer fields come first; the 
remaining numeric fields, if any, are packed so as to optimize the space used. 


Note that the user can define how user datatypes are to be printed via defprint (Section 14), and 


how they are to be evaluated by the interpreter via defeval (Section 8), and how they are to be 


compiled by the compiler via compiletypelst (Section 18. . 


3.3 STORAGE ALLOCATION AND GARBAGE COLLECTION 


In the following discussion, we will speak of a quantity of memory being assigned to a particular 
data-type, meaning that the space is reserved for storage of elements of that type. Allocation will 


refer to the process used to obtain from the already assigned storage a кре location for 


storing one data element. 


A small amount of storage is assigned to each data-type when Interlisp-10 is started; additional 
storage is assigned only during a garbage collection. 


The page is the smallest unit of memory that may be assigned for use by a particular data-type. 
For each page of memory there is a one word entry in a type table. The entry contains the 
data-type residing on the page as well as other information about the page. The type of a pointer 
is determined by examining the appropriate entry in the type table. 


Storage is allocated as is needed by the functions which create new data elements, such as cons, 
pack, mkstring. For example, when a large integer is created by iplus, the integer is stored in the 
next available location in the space assigned to integers. If there is no available location, a garbage 
collection is initiated, which may result in more storage being assigned. 


The storage allocation and garbage collection methods differ for the various data-types. The major 
distinction is between the types with elements of fixed length and the types with elements of 
arbitrary length. List nodes, atoms, large integers, floating point numbers, and string pointers are 
fixed length; all occupy 1 word except atoms which use 3 words. Arrays, pnames, and strings 
(string characters) are variable length. 


Elements of fixed length types are stored so that they do not overlap page boundaries. Thus Ше 
pages assigned to a fixed length type need not be adjacent. If more space is necded, any empty 
page will be used. The method of allocating storage for these types employs a free-list of available 
locations; that is, cach available location contains a pointer to the next available кик A new 
element is stored at the first location on the frec-list, and the free-list pointer is updated. 


Elements of variable length data-types are allowed to overlap page boundaries. Consequently all 
pages assigned to a particular variable length type must be contiguous. Space for a new element is 
allocated following the last space used in the assigned block of contiguous storage. 


18 


First a page is chosen (see CONS for details), then the free list for that page is used. Lists are the only data-type 
which opcrate this way. | 


3.9 


The allocation routine for list nodes is more complicated. Each page containing list nodes has a separate free list. | 


+++ 


+ + + + 


Section 3: Data types, Storage Allocation, Garbage Collection, and Overlays 


When Interlisp-10 is first called, a few pages of memory are assigned to each data-type. When the 


allocation routine for a type determines that no more space 15 available in the assigned storage for 


_ that type, a garbage collection is initiated. Тһе garbage collector determines what data is currently 


in use and reclaims that which is no longer in use. A garbage collection may also be initiated by 
the user with the function reclaim (Section 10). 


Data in use (also called active data) is any data that can be "reached" from the currently running 
program (1.с., variable bindings and functions in execution) or from atoms. То find the active data 
the garbage collector "chases" all pointers, beginning with the contents of the push-down lists and 


. the components (1.е., car, cdr, and function definition seis of all atoms with at least one non-trivial 


component. 


When a previously unmarked datum is encountered, it is marked, and all pointers contained in it 
are chased. Most data-types are marked using bit tables; that is tables containing onc bit for each 
datum. Arrays, however, are marked using a half-word in the array header. 


When the ini and chase process is completed, unmarked (and therefore unused) space is 
reclaimed. Elements of fixed length types that are no longer active are reclaimed by adding their 
locations to the free-list for that type. This free list allocation method permits reclaiming space 


. without moving any data, thereby avoiding the time consuming process of updating all pointers to 


moved data. To reclaim unused space in a block of storage assigned to a variable length type, the 
active elements are compacted toward the beginning of the storage block, and then a scan of all 


active data that can contain pointers to the moved data is performed to update the pointers, 13 


Whenever a garbage collection of any type is initiated, unused space for all fixed length types is 
reclaimed since the additional cost is slight. However, space for a variable length type is reclaimed 
only when that type initiated the garbage collection. 


If the amount of storage reclaimed for the type that initiated the garbage collection is less than the 
minimum frce storage requirement for that type, the garbage collector will assign enough additional 
storage to satisfy the minimum free storage requirement. The minimum free storage requirement 
for each data may be set with the function minfs (Section 10). Тһе garbage collector assigns 
additional storage to fixed length types by finding empty pages, and adding the appropriate size 
elements from each page to the free list. Assigning additional storage to a variable length type 
involves finding empty pages and moving data so that the empty pages are at the end of the block 
of storage assigned to that type. 


In addition to increasing the storage assigned to the type initiating a garbage collection, the garbage 
collector will attempt to minimize garbage collections by assigning more storage to other fixed 
length types according to the following algorithm.” If the amount of active data of a type. has 
increased since the last garbage collection by тоге than 1/4 of the minfs value for that type, 


19 If Interlisp-10 types the message ARRAYS FOULED during a garbage collection, it means that an array header Наз. 
been clobbered and no longer makes sense. This can be due to hardware malfunction, or an as yet undiscovered 
bug in Interlisp. The best thing to do under these circumstances is to give up and start over with a fresh system or 
sysout. | | 

20 те "type of a garbage collection" or the "type that initiated a garbage collection" means either the type that ran out 
of space and called the garbage collector, or the argument to reclaim. 

21 


We may expcriment with different algorithms. 
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storage is increased (if necessary), to attain the тїп value. If active data has increased by less 
than 1/4 of the minfs value, available storage is increased to 1/2 minfs. If there has been no 
increase, no more storage is added. For example, if the minfs setting is 2000 words, the number of 
active words has increased by 700, and after all unused words have been collected there are 1000 
words available, 1024 additional words (two pages) will be assigned to bring the total to 2024 words 
available. If the number of active words had increased by only 300, and there were 500 words 
available, 512 additional words would be assigned. 


3.4 SHARED INTERLISP-10 


The Interlisp-10 system initially obtained by the user is shared; that is, all active users of 
Interlisp-10 are actually using the same pages of memory. As a user adds to the system, private 
pages are added to his memory. Similarly, if the user changes anything in the original shared 
Interlisp-10, for example, by advising a system function, a private copy of the changed page is 
created. 


In addition to the swapping time saved by having several users accessing the same memory, the 
sharing mechanism permits a large saving in garbage collection time, since we do not have to 
garbage collect any data in the shared system, and thus do not need to chase from any pointers on 
shared pages during garbage collections. | 


This reduction in garbage collection time is possible because the shared system usually is not 
modified very much by the user. If the shared system is changed extensively, the savings in time 
will vanish, because once a page that was initially shared is made private, every pointer on it must 
be assumed active, because it may be pointed го by something in the shared system. Since every 
pointer on an initially shared but now private page can also point to private data, they must always 
be chased. 


A user may create his own shared system with the function makesys. If several people are using 
the same system, making the system be shared will result in a savings in swapping time. Similarly, 
if a system is large and seldom modified, making it be shared will result in a reduction of garbage 
collection time, and may therefore be worthwhile even if the system is only being used by one 
user. 


makesys[file] creates a saved file in which all pages in this system, including 
private user pages, are made read execute, i.e. shared. This system 
can then be run via the TENEX command RUN or GET and 
START. 


For example, new Interlisp-10 systems are brought up by loading the appropnate compiled ша 
and then performing makesys[LISP.SAV]? 


herald[string] makes string be the 'herald' for the system, i.e. the message printed 
when the system is first started. Primarily for use in conjunction 
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makesys is also advised (sce section 19) to set the variable makcsysdate to (DATE), i.e. the time and date the system 
was made. | 
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with makesys.?? 


„3.5 THE INTERLISP-10 SWAPPER^ 


Interlisp-10 provides a very large auxilary address space exclusively for swappable arrays (primarily 
compiled function definitions). In addition to the 256K of resident address space, this "shadow 
space" can currently accomodate an additonal 256K words, can casily be expanded to 3.5 million 
words, and with some further modifications, could be expanded to 128 million words. Thus, the 
overlay system provides essentially unlimited space for compiled code. 


Shadow space and the swapper are intended to be more or less transparent to the user. However, 
this section is included in the manual to give programmers a reasonable feeling for what overlays 
are like, without getting unnecessarily technical, as well as to document some new functions and 
system controls which may be of interest for authors of exceptionally large systems. 


3.4.1 OVERLAYS 


The shadow space is a very large auxiliary address space used exclusively for an Interlisp data-type - 
called a swappable array. The regular address space is called the "resident" space to distinguish it - 
from shadow space. Any kind of resident array - compiled code, pointer data, binary data, or a 
hash array - can be copied into shadow space ("made swappable"), from which it is referred to by 
а one-word resident entity called a handle. The resident space occupied by the original array сап | 
then be garbage collected normally (assuming there are no remaining pointers to it, and it has not 
been made shared by am makesys S) Similarly, a swappable array can be made resident again at any 
time, but of course this requires (re)allocating the necessary resident space. 


The main purpose and intent of the swapping system is to permit utilization of swappable arrays 
directly and interchangeably with resident arrays, thereby saving resident space which is then 
available for other data-types, such as lists, atoms, strings, etc. 


This is accomplished as follows: А section of the resident address space is permanently reserved for | 


23 makesys is advised to set the variable heraldstring to the concatenation of "Interlisp-10", the month and day 
of the makesys, and "..." and to call herald on this string. Alternatively, makesys can be given as a second argument. 
a string to be used send of "Interlisp-10", eg. makesys[STREK. SAV; STAR- TREK] would cause the message 
STAR- TREK followed by the date and "..." to be printed when STREK.SAV was run. 


24 Тһе Interlisp-10 swapper was designed by Е. 1. Wegbreit SREE and J. W. Goodwin (BBN), and implemented by | 
J. W. Goodwin. 


25 Since compiled code arrays point to atoms for function names, and strings for error messages, not to mention the 
fact that programs usually have data base, which are typically lists rather than arrays, there is still a very real and 
finite limit to the total size of programs that Interlisp-10 сап accomodate. However, since much of the system and 
user compiled code can be made swappable, there is that much morc resident space available for these other 
data- “types. 
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a swapping buffer. When a particular swappable array is requested, it is brought (swapped) in by 
mapping or overlaying the pages of shadow space in which it lics onto a section of the swapping 
buffer. This process is the swapping or overlaying from which the system takes its name. The 
array is now (directly) accessible. However, further requests for swapping could cause the array to 
be overlaid with something else, so in effect it is liable to go away at any time. Thus all system 
code that relates to arrays must recognize handles as a special kind of array, fetch them into the 
buffer (if not already there), when necessary check that they have not disappeared, fetch them back 
in if they have, and even be prepared for the second fetch to bring the swappable array in at a 
different place than did the first. 


The major emphasis in the design of the overlay system has been placed on running compiled 
code, because this accounts for the overwhelming majority of arrays in typical systems, and for as 
much as 60% of the overall data and code. The system supports the running of compiled code 
directly from the swapping buffer, and the function calling mechanism knows when a swappable 
definition is being called, finds it in the buffer if it is already there, and brings it in otherwise. 
Thus, from the user’s point of view, there is no need to distinguish between swappable and 
resident compiled definitions, and in fact ccodep will be true for either. 


3.4.2 EFFICIENCY 


Once of the most important design goals for the overlay system was that swappable code should 
not execute any extra instructions compared to resident code, once it had been swapped in. Thus, 
the instructions of a swappable piece of code are identical (exce ер! for two instructions at the entry 
point) to those of the resident code from which it was copied,*’ and similarly when a swappable 
function calls another function (of any kind) it uses the exact same calling sequence as any other 
code. Thus, all costs associated with running of swappable code are paid at the point of entry | 
(both calling and returning).28 


The cost of the swapping itself, i.e. the fetch of a new piece of swapped code into the buffer, is 
even harder to measure meaningfully, since two successive fetches of the same function are not the 
same, due to the fact that the instance created by the first fetch is almost certain to be resident 
when the second is done, if no swapping is done in between. Similarly, two successive PMAP's 
(the Tenex operation to fetch one page) are not the same from one moment to another, even if the 
virtual state of both forks is exactly the same - a difficult constraint to meet in itself.2? 29 Thus, all 
that can be reported is that empirical measurements and observations have shown no consistent 
slowdown in performance of systems containing swappable functions viz a viz resident functions. 


26 Initially 64 512 word pages, but can be changed via the function setsbsize described below. 


27 The relocatable instructions are indexed by а base register, to make them run equally well at апу location in the 


buffer. The net slowdown due to this extra level of indirection is too small (о measure accurately i in the overall 
running of a program. On analytical grounds, one would expect it to be around 2%. 
28 If the function in question does nothing, e.g. а compiled (LAMBDA NIL NIL), it costs approximately twice as much 
to enter its definition if it is swappable as compared to resident. However, very small functions are normally not 
made swappable (see mkswapp, page 3.14), because they don’t save much space, and are (typically) entered 
frequently. Larger programs don't exhibit a measurable slow down since they amortize the entry cost over longer 
runs. 
29 The cost of fetching is probably not in the mapping opcration itsclf but in the first reference to the page, which has 
a high probability of faulting. This raises the problem of measuring page fault activity, another morass of 
. uncertainty. 


3.13 


-Section 3: Data types, Storage Allocation, Garbage Collection, and Overlays 


3.4.3 SPECIFICATIONS 


Associated with the overlay system is а datatype called a swparray, (type name SWPARRAYP), which 
Occupies one word of resident space, plus however much of shadow space needed for the body of 
the array. arglist, fntyp, nargs, getd, ри, argtype, arraysize, changename, calls, break, advise, and 
edita all work equally well with swappable as resident programs. ccodep is true e for all П compiled 
functions/definitions. 


 swparrayplx] Analogous to arrayp. Returns x if x isa swappable array and, NIL 
| | otherwise. 


scodep[x] | analagous to ccodep. Returns Т if x is ог has а swapped compiled 
| definition. | 


++ 


mkswap[x] | | . If x is a resident array, returns a swappable array which is а сору of 
í I x. ІҒх is a literal atom and ссодерјк) is true, its definition is 
copied into a swappable array, and it is (undoably) redefined with 

the latter. The value of mkswap is x. 


mkunswap[x] | — the inverse of m mkswap. x is either a swappable array, or an atom 
| Е with swapped definition on its CODE кореп; 


mkswapp[fname;cdef] All compiled definitions begin life as resident arrays, whether they 
| . are created by load, ог by compiling to core. Before they аге 
stored away into their atom’s function cell, mkswapp is applied to 

the atom and the array. If the value of mkswapp is T, the 

definition is made swappable; otherwise, it is left resident. By 

redcfining mkswapp or advising it, the user can completely control 

the swappability of all future definitions as they are created. The 

initial definition of mkswapp will make a function swappable if (1) 

noswapflg is NIL, and (2) the name of the function is not on 

noswapfns, and (3) the size of its definition is greater than 

mkswapsize words, initially 128. | 


setsbsize[n] | | Sets the size of the swapping buffer to n, a number of pages. 
| . Returns Ше previous value. setsbsize[] returns the current size 
without changing 1.30 


» Currently, the system lacks error recovery routines for situations such as a call to a swappable function which is too 


big for the swapping buffer, or when the size is zero. Therefore, setsbsize should be used with care. 
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SECTION4 | | 
FUNCTION TYPES AND IMPLICIT PROGN 


In Interlisp, each function may independently have: 


a. its arguments evaluated or not evaluated; 
b. a fixed number of arguments or an indefinite number of arguments; 
с. be defined by ап Interlisp expression, by built-in machine code, ог by compiled 


machine code. 


Hence there are twelve function types (2 x 2 x 3). 


4.1 EXPRS 


~ 


Functions defined by Interlisp expressions are called exprs. Exprs must begin with either LAMBDA 


or NLAMBDA,! indicating whether the arguments to the function are to be evaluated or not 


evaluated, respectively. Following the LAMBDA or NLAMBDA in the expr is the "argument list", 
which is either | 


(1) a list of literal atoms or NIL (fixed number of arguments); or | 
(2) апу literal atom other than NIL, (indefinite number of arguments). 2 


Case (1) corresponds to a function with a fixed number of arguments. Each atom in the list is the 
name of an argument for the function defined by this expression. When the function is called, its 


arguments will be evaluated or not evaluated, as dictated by whether the definition begins with . 


LAMBDA or NLAMBDA, and then paired with these argument names) This process is called 


Where unambiguous, the term expr is used to refer to either the function, or its definition. 


2 Anything else will cause an ARG NOT LITATOM error, e.g. (LAMBDA "FOO" --), or (LAMBDA (X 7 --). In 
addition, if NIL or T is used as an argument name, the error ATTEMPT TO BIND NIL OR T is generated. 


Note that the function itself can evaluate selected arguments by calling eval. Іп fact, since the function type can 
specify only that all arguments are to be evaluated or none are to be evaluated, if it is desirable to write a function 
which only evaluates some of its arguments, c.g. setq. the function 15 defined as an nlambda, i.e. no arguments are 
evaluated in the process of calling the function, and then included in the definition itself arc the appropriate calls to 
eval. In this case, the user should also put on the property list of the function under the property INFO the value 
EVAL to inform the various system packages such as DWIM, CLISP, PRINTSTRUCTURE, etc., that this function in 
fact does evaluate its arguments, even though it is an nlambda. 
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"spreading" the arguments, and the function is called а spread-LAMBDA or а spread-NLAMBDA, ог 
simply a spread function. 


Case (2) corresponds to a function with an indefinite number of arguments. Such a function is 
called a nospread function. If its definition begins with NLAMBDA, the atom which constitutes its 
argument list 15 bound to the list of arguments to the function (unevaluated). For example, if FOO 
is defined by (NLAMBDA Х --), when (FOO THIS 15 A TEST) is evaluated, X will be bound to 
(THIS IS A TEST). 


If a nospread function begins with a LAMBDA, indicating its arguments are to be evaluated, each of 
its n arguments are evaluated and their values stored on the pushdown list. The atom following 


the LAMBDA is then bound to the number of arguments which have been evaluated. For example, 


МБ тсс eb Re A ER SFE Пор. 


if FOO is defined by (LAMBDA Х --) when (FOO A В С) is evaluated, А, В, and С are evaluated 
and X is bound to 3. A built-in function, arg[atm;m], is available for computing the value of the 
mth argument for Ше lambda-atom variable atm. агр is described in section 8. | 


4.2 COMPILED FUNCTIONS 


Functions defined by expressions can be compiled by the Interlisp compiler, as described in section 
18, "The Compiler and Assembler". In Interlisp-10, functions may also be written directly in 
machine code using the ASSEMBLE directive of the compiler. Functions created by the compiler, 
whether from S-expressions or ASSEMBLE directives, are referred to as compiled functions. In 
Interlisp-10, compiled functions may be resident or swappable, as described in section 3. 


4.3 FUNCTION TYPE 


The function fntyp returns the function type of its argument. The value of fntyp is one of the 
following 12 types: E 


EXPR CEXPR SUBR 
FEXPR CFEXPR FSUBR 
EXPR* CEXPR* SUBR* 
FEXPR*- CFEXPR* FSUBR* 


The types in the first column are all defined by expressions. The types in the second column are 
compiled versions of the types in the first column, as indicated by the prefix C. In the third 
column are the parallel types for built-in subroutines. Functions of types in the first two rows 
have a fixed number of arguments, 1.е., are spread functions. Functions іп the third and fourth 
rows have an indefinite number of arguments, as indicated by the suffix *. The prefix F indicates 
no evaluation of arguments. Thus, for example, а CFEXPR* is a compiled form of а nospread- 
NLAMBDA. 


A standard feature of the Interlisp system is that no error occurs if a spread function is called with 
foo many or too few arguments. If a function is called with too many arguments, the extra 
arguments are evaluated but ignored. If a function is called with too few arguments, the 
unsupplied ones will be delivered as NIL. In fact, the function itself cannot distinguish between 
being given NIL as ап argument, and по being given that argument, eg., 
(FOO) and (FOO NIL) are exactly the same for spread functions. | | | 
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PROGN 


4.4 PROGN 


progn is a function of an arbitrary number of arguments. progn evaluates the arguments іп order 
and returns Ше value of the last, 1.е., it is an extension of the function prog2 of LISP 1.5. Both 
cond and lambda/nlambda expressions have been generalized to permit "implicit progns" as 
described below. | | | 


4.5 IMPLICIT PROGN 


The conditional expression has been generalized so that each clause may contain n forms (n > 1) 
which are interpreted as follows: 


(COND 
(P1 £11 £12 £13) 
(P2 E21 E22) [1] 
(P3) | 
(Р4 Е41)) 


will be taken as equivalent to (in LISP 1.5): 


(COND 
(РТ (PROGN E11 E12 Е13)) 
(P2 (PROGN E21 E22)) 
(P3 P3) [2] 
(P4 E41) 
(T NIL)) 


Note however that P3 is evaluated only once in [1], while it is evaluated a second time if the 
expression is written as in [2]. Thus a clause in a cond with only a predicate and no following 
expression causes the value of the predicate itself, if non-NIL, to be returned. Note also that NIL 
is returned if all the predicates have value NIL, i.e., the cond "falls off the end". No error is 
generated. 
LAMBDA and NLAMBDA expressions also allow implicit progn's; thus for example: 

(LAMBDA (V1 V2) (F1 V1) (F2 V2) NIL) 
is interpreted as: 


(LAMBDA (V1 V2) (PROGN (F1 V1) (F2 V2) NIL)) 


The value of the last expression following LAMBDA (or NLAMBDA) is returned as the value of the 
entire expression. In this example, the function would always return NIL. 
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SECTION 5 
PRIMITIVE FUNCTIONS AND PREDICATES 


5.1 PRIMITIVE FUNCTIONS 


car[x] car gives the first element of a list x, or the left element of a dotted 
pair x. car of NIL is always NIL. For all other nonlists, e.g., 
atoms, strings, arrays, and numbers, the value is undefined (and in 
some implementations may generate an error). 


сах] cdr gives the rest of a list (all but the first element). This is also. 
| the right member of a dotted pair. cdr of NIL is always NIL. - The | 
value of cdr is undefined for other nonlists. 


caar[x] = сацсацх]] All 30 combinations of nested cars and cdrs up to 4 deep 


cadr[x] = car[cdr[x]] . are included in the system. АП are compiled 
cddddr[x] = open by the compiler. 


cdr[cdr[cdr[cdi[x ] ]]] 


cons[x:y] cons constructs a dotted pair of x and y. If y is a list, x becomes 
the first element of that list. To minimize drum accesses the 
following algorithm is used in Interlisp-10, for finding a раве оп 
which to put the constructed Interlisp word. 
cons[x;y] is placed 
1) on the page with y if y is a list and there is room; otherwise 
2) on the page with x if x is a list and there is room; otherwise 


3) on the same page as the last cons if there is room; otherwise 


4) on any page with a specified minimum of storage, presently 16 LISP words. 
conscount[-] value is the number of conses since this Interlisp was started up. 


rplacd[x;y] Places the pointer y in cdr of the cell pointed to by x. Thus it 
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physically changes the internal list structure of x, as opposed to 


cons which creates а new list element. The only way to get a. 
circular list is by using rplacd to place a pointer to the beginning of 
a list in a spot at the end of the list. 


The value of rplacd is x. An attempt to rplacd NIL will cause an | 
error, ATTEMPT ТО RPLAC NIL, (except for rplacd[NTL ; NIL]). 


An аср: to rplacd any other поп- “list will cause an error ARG 


МОТ LIST. 


| similar to rplacd, but replaces the address pointer of x, ie, саг, 


with у. Тһе value of грѓаса is x. An attempt to rplaca NIL will 


cause an error, ATTEMPT ТО RPLAC NIL, (except for 0 


rplaca[NIL;NIL]) An attempt to грјаса any other non-list will _ 
cause an error, Aa NOT LIST. | 


Convention: Naming a function by prefixing an existing function name with f usually indicates 
that the new function is a fast version of the old, ie, one which has the same deft nition but 
compiles open and runs without any” "safety" error checks. ! 


frplacd[x;y] 


frplaca[x; yl 


+ rplnode[x;a;d] | 


+ mplnode2[x;y] | 


4 трІподсіх;а;а] | 


+ frpInode2{x: yl 


· quote[x] 


error, and onc that 
PARENTHESIS ERROR. 


EP N ЛЭС e c/u е аял iiem Lon. Ноа - 


_ Has the same definition as rplacd but compiles open as one 


instruction. Note that no checks are made on x, so that a compiled | 


- frplacd can clobber NIL, producing strange and wondrous е 
—— Similar to frplacd.- 
performs rplaca[x;a], rplacd[x;d], and returns x. 
EM rplaca[x;carfy]], rplacd[x;cdi[y]] and returns x. 


fast version of rplnode that compiles open with no error checks. | 


fast version of rplnode2 that compiles open with no error checks. 


This is a function that prevents its arguments from being evaluated. = 


Its value is x itself, c.g., (QUOTE па is Ғ00.1 


біпсе giving quote more than one argument, е.р., (QUOTE EXPR (CONS X Y)), is almost always a parentheses | 
would otherwise ро undetected, quote itself gencrates an error іп this case, 
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kwotce[x] Value is an expression which when evaluated yields x. If x is NIL 
or a number, this is x itself. Otherwise, (LIST (QUOTE QUOTE? 
x). For example, ifx=A, and y=B, then 
(KWOTE (CONS x y)) = (QUOTE (А. В)). 


cond|cy ;c3;...;Cg] = The conditional function of Interlisp, cond, takes an indefinite 
number of arguments с1,с?, .. сұ, called clauses. Each clause с; is 
а list (еј, ... е) of n >_1 items, where the first element is the 
predicate, and. the rest of the elements the consequents. Тһе 
operation of cond can be paraphrased а 
ТЕ e44 THEN е та. ELSEIF е,» THEN е 


The clauses аге considered іп sequence as follows: Ше first 
expression еј; of the clause с, is evaluated and its value is classified 
as false (equal to NIL) or true (not equal to NIL). If the value of 
еј, is true, the expressions eo, ... €,; that follow in clause сі аге 
evaluated in sequence, and the value of the conditional is the value 
of ер, the last expression in the clause. In particular, if n— 1, ie., 
if there is only one expression in the clause c;, the value of the 
conditional is the value of ен. (which is evaluated only once). 


If ej; is false, then the remainder of clause c, is ignored, and the 
next clause c; , | is considered. If no is true for a any clause, the 
| value of the conditional expression is N di | 


selectq[x clause; ;clause»;...;clause,; default] 

selects a form or sequence of forms based on the value of its ; first 
argument x. Each clause, is a list of the form (S; еј; e9; . 

where s; is the selection key. The operation of! se оска сап yi) | 
paraphrased as: 

IF х=54 THEN e4, ... e 

ELSEIF X=So THEN ... ЕЕЌЕ default. 


If s; is an atom, the value of x is tested to see if it is ед to s; (not 
evaluated). If so, the expressions еј; ... еј аге “evaluated in 
sequence, and the value of the selectq is e value of the last 
expression evaluated, i.e., ер. | | 


If s; is a list, the value of x is compared with cach element (not - 
evaluated) of 5, and if x is eq to any one of them, then еј, to Ski " 
are evaluated i in turn as above. 


If clause; is not sclected in one of the two ways described, 
clause; 41 is tested, etc., until all the clause’s have been tested. If 
none is sclected, the value of the selectq is the value of default. 5 
default must be present. 


An example of the form of a selectq is: 
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ргов1[хү;х2;...;х] 


progn[x4:x5;..:x] 


prog[varslst;e; ;e5;...;eg] - 
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ГЗЕГЕСТО (CAR X) 
(Q (PRINT FOO) 


С (FIE X)) 
((A E I O U) 
(VOWEL X)) 
( COND 
((NULL X) 
NIL) 


x (QUOTE STOP] 


which has two cases, Q 200 (A E I O Ч) anda default condition 
which is a cond. | 


selectq compiles open, and is therefore very fast; however, it will 


. not work if the value of x is а list, a large integer, or floating pont 


number, since selectq uses eq for all comparisons. 


| evaluates its armani in order, that is, first xj, then x», etc, and 
returns Ше value of its firt argument x), ер, 


(PROGI X (SETQ X Y)) sets x to y, and returns x’s original 
value. | | 


progn evaluates each of its arguments іп order, and returns the 


value of its last argument as its value. progn is used to specify 
. more than one computation where the syntax allows only one, е.2., 


(SELECTQ . . (PROGN ...)) allows evaluation of several 
expressions as the default condition for a selectq. | 


.. This function allows the user to write an ALGOL-like program 


containing Interlisp expressions (forms) to be executed. The first 
argument, varlst, is a list of local variables (must be NIL if no 
variables are used). Each atom in varlst is treated as the name of a 


-local variable and bound to NIL. varist can also contain lists of the 


form (atom form). In this case, atom is the name of the variable 
and is bound to the value of form. The evaluation takes place 
before any of the bindings ае performed, ер, 
(PROG ((X Y) (Y X)) ...) will bind x to the value of y and 
y to the (original) value of x. An attempt to usc anything other 
than a literal atom as a prog variable will cause an error, 


ARG NOT LITATOM. An attempt to use NIL or T as а prog 


variable will cause an error, ATTEMPT TO BIND NIL OR T. 


The rest of the prog is a sequence of non-atomic statements (forms) 
and atomic symbols, i.c. litatoms, used as labels for go. The forms 
arc evaluated sequentially; the labels serve only as markers. The 
two special functions go and return alter this flow of control as 
described below. ‘The value of the prog is usually specified by the 
function return. If no return is executed, i.c., if the prog "falls off 
the end," the value of the prog is NIL. 
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go[x] во is the function used to cause a transfer in a prog. (GO L) will 
cause the program to continue at the label L. A go can be used at 
any level іп a prog. If the label is not found, go will search higher 
progs within — the same function, e.g., 
(PROG -- A -- (PROG -- (GO A))). If the label is not 
found in the function in which the prog appears, an error is 
generated, UNDEFINED OR ILLEGAL GO. 


return[x] A return is the normal exit for a prog. Its argument is evaluated 
and is the value of the prog in which it appears. 


If a go or return is executed in an interpreted function which is not a prog, the go or return will 
be executed in the last interpreted prog entered if any, otherwise cause an error. 


go or return inside of a compiled function that is not a prog is not allowed, and will cause an 
error at compile time. 


As a corollary, go or return in a functional argument, e.g., to sort, will not work compiled. Also, 
since nlsetq's and ersetq's compile as separate functions, a go or return cannot be used inside of a 
compiled nlsetq or ersetq if the corresponding prog is outside, i.e., above, the nlsetq or ersetq. 


set[x;y] | This function sets x to y. Its value is y. If x is not a literal atom, 
causes an error, ARG NOT LITATOM. If x is NIL, causes an error, 
ATTEMPT TO SET NIL. Note that set is a normal lambda-spread 
function, i.e., its arguments are evaluated before it is called. Thus, 
if the value of x is c, and the value of y is b, then set[x;y] would 
result in c having value b, and b being returned as the value of set. 


setq[x;y] An nlambda version of set: the first argument is not evaluated, the 
second is.) Thus if the value of X is C and the value of Y is B, 
(SETQ X Y) would result in X (not C) being set to B, and B 
bcing returned. If x is not a literal atom, an error is generated, 
ARG NOT LITATOM. If x is NIL, the error ATTEMPT TO SET 
NIL is generated. 


ѕсіда[х;у] Like setq except that neither argument is 
evaluated, e.g., (5ЕТ00 X (А B C)) sets x to (A B C). 


gcettopval[atm] returns top level value of atm from its value cell (even if NOBIND), 
regardless of any intervening bindings. Interpreted, generates ап 
error, ARG NOT LITATOM, if atm is not a literal atom. 


Since sctq is ап nlambda, neither argument is evaluated during the calling process. However, setq itself calls суа! on 
its second argument. Note that as а result, typing (ФЕТО var form) and SETQ(var form) to lispx is equivalent: in 
both cases var is not evaluated, and form is. 
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settopval[atm; val] Sets top level value of atm, regardless of any intervening bindings, 


ic. stores val in value cell of atm. Value is val. Interpreted, | 


generates an error ATTEMPT TO SET NIL, if atm= NIL, or ARG 
NOT LITATOM, if atm is not a literal atom. 


Note: gettopval and settopval are rarely used in a system which employs shallow binding such as 


Interlisp-10, as it is more economical to simply rebind variables. In a deep bound system, 
gettopval and settopval are very efficient since they do not have to search the stack, but can simply 


access the value cell directly. In a shallow bound system, the opposite is true: gettopval and 


settopval have to search the stack for rebindings and hence can be quite expensive. 


In order to provide a convenient way for both deep and shallow bound systems of referring to | 


what are conceptually global variables, the following functions are provided: 


getatomval[atm] in shallow system, such as Interlisp-10, same as- evalv[atm], or 


simply atm. In deep bound system, same as es 


setatomval[atm; val] _ in shallow bound system, same as set, in dees bound stem same 
| | as settopval. | 


In other words, getatomval. and setatomval always access a variable S value cell, 3 regardless of v 


whether the system is deep or shallow bound. 


rpad[x ;у] | | An nlambda function like 5 Бе ехсері always works on top level | 


value of x, i.e., on the value се. 


rpaqa[x;y] | 1 An nlambda function like setqq for top level values. 


град and града are used by the file package (Scction 14). Both град and града generate errors if 


x is not a literal atom. Both are affected by the value of dfnflg (Section 8). If dfnflg=ALLPROP _ 
(and the value of x is other than NOBIND), instead of setting x, the corresponding value 15 stored | 


оп Ше ргорецу list of x under the property VALUE. Both are undoable. 


addtovar[var;xj;x;.:xg] | nlambda, nospread function. Each Xi that is not a member of the 
| valuc of var is added to it, Те. after addtovar completes, the value 


of var will be union[list[x; ; хә Хх]: var]. addtovar is used by 


prettydef for implementing the ADDVARS command. It performs 
some file package (sce Section 14) related operations, i.e. "notices" 
that var has been changed. Value is var (not the value of var). 


As described in Section 3, an atom which has not previously becn used as a variable does not have a value cell in 
Interlisp-10. However, from the standpoint of getatomval and evalv the atom looks like it has a value cell which 
contains the atom NOBIND. | 
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CHANGING AND RESTORING SYSTEM STATE 


In Interlisp, a computation can be interrupted/aborted at any point due to an error, or more 
forcefully, because а control-D was typed, causing return to Ше top level. This situation creates 
problems for programs that need to perform a computation with the system in a "different state", 
e.g., different radix, input Ме, readtable, etc. but want to "protect" the calling environment, 1.е., be 
able to restore the state when the computation has completed. While errors can be "caught" by 
errorsets, control-D cannot. Thus the system may be left in its changed state as a result of the 
computation being aborted. The following functions address this problem:? 


resetlst[resetx] nlambda, nospread. resetx is a list of forms. resetlst sets up an 
errorset so that any reset operations performed by resetsave (see 
below) are restored when the evaluation of resetx has been 
completed (or an error occurs, or a control-D is typed). If no error 
Occurs, the value of resetlst is the value of the last form on resetx, 
otherwise resetlst generates an error (after performing the EPA 
restorations). resetlst compiles open. 


resetsave[resetx] nlambda, nospread function for use under a resetlst.© If car of 
resetx is atomic, resets the top level value of car of resetx to the 
value of cadr of гезе{х ер, 
(RESETSAVE LISPXHISTORY EDITHISTORY) resets the value 
of lispxhistory to be edithistory and provides for the original value 
of lispxhistory to be restored when Ше resetlst pon среганов, 
(or an error occurs, ог а control-D is (уред). | 


If саг ОҒ resetx is not atomic, it is а form that is evaluated. If сдг — 
of resetsave is NIL, е.р., (RESETSAVE (RADIX 8)), the form 
must return as its value its "former state", so that the effect of 
evaluating the form can be reversed, and the system state can be 
restored, by applying car of the form to the value of the form, e.g., 
(RESETSAVE (RADIX 8)) performs (RADIX 8), and provides 
for radix to be reset to its original value when the resetlst completes - 
by applying radix to the value returned by (RADIX 8). 


іе., not conveniently. The program could of course redefine control-D as a чепщенирь check for it reenable it, 
and call reset or something similar. 


Note that these functions do not (cannot) handle the situation where their environment is exited via anything other 
than a normal return, an error, or a reset. E.g. a reteval, retfrom, resume, etc., will never be seen. 


++ 


resetsave can be called when not under a resetlst. In this case, the restoration will be performed at the next RESET, 
i.e., control-D or call to reset. In other words, there is an "implicit" resetlst at the top level in evalqt. 


This use is somewhat anachronistic in Interlisp- 10 in that in a shallow bound system, it is sufficient to simply rebind 
the variable. Furthermore, if there are any rebindings, the resetsave will лог affect the most recent к but will 
change only the top level value, and therefore probably not have the intended effect. | 


except if car of the form is sctg, the setq is transparent for the purposes of resctsave, i.e. the user could also have 
written (RESETSAVE (SETQ X (RADIX 8))), and restoration would be performed bv applying radix, not s setq, 
to the previous value of radix. 


+++ +++ 
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For functions which do not return their "previous setting", the 
restoring expression can be specified as the value of the second 
argument to resetsave, which in this case is evaluated before the - 
first argument, c.g., 

[RESETSAVE(SETBRK --)(LIST( QUOTE SETBRK ) (GETBRK]? 
will restore the break characters by applying setbrk to the value 
returned by (GETBRK), which was computed before the ІЗЕТВЕК | 
--) expression was evaluated. 


(RESETSAVE NIL form) is permissible. It simply — that | 
the value of form be treated as a restoration expression, e.g., — 
(RESETSAVE NIL (LIST (QUOTE CLOSEF) FILE)) | will 
cause file to be closed when the resetlst that the resetsave is under 
completes (or an error occurs or a control-D is typed). 


 resetsave compiles open. Its value is not a "useful" quantity. 


resetvar[var;newvalue;form] ^ Nlambda function. Simplified form of resetlst and resetsave for 
resetting | and restoring global variables. 10 Equivalent to 
(RESETLST (RESETSAVE var newvalue) form), e.g., | 
(RESETVAR LISPXHISTORY EDITHISTORY (ЕОО)) resets 
 lispxhistory to Ше value of edithistory while evaluating (ЕОО). 
resctvar compiles open. If no error occurs, its value is the value of 
form. | 


resetvars[varslst;ej;e5;..:eg] ^ nlambda function, similar to prog, except the variables in varslst are 
ја | = global variables. In a shallow bound system (Interlisp- 10) reset resetvars 
and prog are identical! In a deep bound system, each variable is 
"rebound" using resetsave. | | 
resetvars, like getatomval and setatomval, is provided to permit compatibility (i.e. transportablility) · 
between a shallow bound and deep bound system with respect to conceptually global variables. 
шна о; Шы form»;...;formg] | 
Slambda function. Simplified form of resctlst and resetsave for 
resctting a system state when the corresponding. function returns as 
its value the "previous setting." Equivalent - to 
(RESETLST (RESETSAVE resetform) form, form» ... form,), e.g. 
(RESETFORM (RADIX 8) (F00)). resetform compiles open. If 
no error occurs, its value is the value returned by formy 
9 Note that the restoration expression is sull "evaluated" by applying its car to its cdr. 
Unnecessarily expensive in a shallow bound system as the variable can simply be rebound. 


+ i except that the compiler insures that variables bound in a resctvars are declared as SPECVARS (sce Section 18). 
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For some applications, the restoration operation must be different depending on whether the 
computation completed successfully or was aborted by an error or control-D. То facilitate this, 
while the restoration operation is being performed, the value of resetstate will be bound to NIL, 
. ERROR, or RESET, depending on whether Ше exit, was normal, due to an error, or reset (1е., 
control-D, or in Interlisp-10, control-C followed by reenter). For example, 


(RESETLST (RESETSAVE (INFILE X) (LIST '[LAMBDA (FL) 
(AND (EQ RESETSTATE 'RESET) (CLOSEF FL) (DELFILE FL] х) 
. forms) 


will cause X to be closed and deleted only if a control-D was typed during Ше execution of forms, | 


For convenience in specifying complicated restoring expressions, the variable oldvalue is bound at 


the time the restoring operation is performed to the value of the saving expression. For example, 


(RESETLST (RESETSAVE (INPUT FL) ' (АМО RESETSTATE (INPUT OLDVALUE )))? 
. forms) 


will restore the primary input file if an error or control-D occurs. 
In addition, the function resetundo, in conjunction with resetlst and resctsave, provides a way of 


specifying that the system be restored to its prior state by undoing the side effects of the 
computations performed under the resctlst.. Undoing and resetundo are described in Section 22. 


5.2 PREDICATES AND LOGICAL CONNECTIVES 


atom[x] | is T if x is an atom; NIL otherwise. 

litatom[x] ^». iş T if x is a literal atom, i.e., an atom and not a number, NIL 
Otherwise, 

numberp[x] is x if x is a number, NIL otherwise. 


Convention: Functions that end in p are usually predicates, ie, they test for some condition. 


stringp[x] is x if x is a string, NIL otherwise? 


12 As mentioned earlier, restoring is performed by applying car of the restoring expression to cdr. This particular 


example works because and applied to (RESETSTATE (INPUT OLDVALUE)) is the same as evang 
(АМО RESETSTATE (INPUT OLDVALUE)). progn also has this property. Note that without using oldvalue, the 
user would have to write m 
(RESETLST 
(SETQ TEM (INPUT FL)) 
(RESETSAVE NIL (LIST '(LAMBDA (FL) (AND RESETSTATE (INPUT n») 
TEM)) 


forms) 


13 


For other string functions, see Section 10. 
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is x if x is an array, NIL otherwise. 


is x if x is a list-structure, i.e., one created by опе or more conses; 
NIL otherwise. 


Note that arrays and strings are not atoms, but are also not lists, ге, both atom апа Шыр will 


nlistp[x] 


eq[x;y] 


пед[х;у] 


пиЩх] 


 not[x] 


пі] 


negate[x] 


egqp[x:y] | 


equal[x;y] 


return NIL when gwen an array or a string. 


not[listp[x]] 


The value of eq is T, if x and y are pointers to the same structure. 


in memory, and NIL otherwise. eq 15 compiled open by the 
compiler. Its value is not guaranteed T for сама! numbers Sn 
are not small integers. see e сар. с 


The value of neq is Т, if x is not eq to y, and NIL otherwise. 
eqix;NIL] | 
same as null, that is еајк: МТ). - 


value is NIL. nill is | useful for those cases where one wants to - 
supply a functional argument which will always return NIL. 00 


returns Ше negation ОЁ | x | For © example: 
negate (MEMBER X Y)]- (NOT (MEMBER. X Y)), | 
negatc[(EQ X Y)]- (МЕО X Y), 


negat[(AND X (NLISTP X))]- (OR (NULL X) (ust X). 


etc. 


The value of сар is T if x and у аге eq, i.e., pointers to the same _ 
structure in memory, or if x and y are numbers and are equal : in 
value.!4 Its value is NIL otherwise. | 


Тһе value of equal is T (1) if x and у are eq, i.c., pointers to the - 
same structure in memory; ог (2) сар, ie. numbers with equal 
value; ог (3) strequal, i.e., strings containing the same sequence of- 


characters; ог (4) lists and car of x is equal to car of y, and cdr of x | 


For more discussion of сар and other number functions, see Section 13, 
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is equal to cdr of y. The value of онај is NIL ошерге mole 
that x and y | do not have to be cq. 


equalall[x;y] like equal, except always descends to atomic levels, i.e. will compare + 
| the contents of arrays, hash arrays, user data types, екс. + 
eqlength[x ;n] equivalent to equal[length[x];n], but more efficient, i.e. stops as soon + 
as it knows that x is longer than n. Note that eglength is safe to use + 
on circular lists, since it is "bounded" by n. + 
equaln[x;y;depth] like equal, for use with (possibly) circular structures. Whenever * 
depth of car recursion plus depth of cdr recursion exceeds depth, * 
equaln does not search further along that chain. If equaln “ 
determines that the expressions x and y are equal, ie. recursion * 
never exceeds depth, value of equaln is T. If they are determined * 
to be unequal, value is NIL. Otherwise, ie. recursion exceeds * 
depth at some point, value |5 ?, ер. * 
сочат ((A)) B);(((Z)) В);21-?. For depth=3, the value ы 
would be NIL оа 
ап ка :Х2:.. ХИ] Takes an indefinite number of arguments (including 0). If all of its 


arguments have non-null value, its value is the value of its last 
argument, otherwise NIL. e.g., and[x;member[x;y]] will have as 15 
value either NIL or a tail of y. and[]- T. Evaluation stops at the . 
first argument whose value is NIL. 


ох Takes an indefinite number of arguments (including 0). Its value is 
2n that of the first argument whose value is not NIL, otherwise NIL if 
all arguments have value NIL. e.g., or[x;numberpl[y]] has its value 
x, y, ог NIL. or{]=NIL. Evaluation stops at the first argument 

whose value is not NIL. 


every[everyx;everyfnl;everyfn2] 
Is T if the result of applying everyfnl to each element in еуегух 15 
true, otherwise NIL. e.g., еуету(Х У 7);АТОМ|-Т. 


every operates by computing everyfnl[car[everyx]]!Ó If this yields 
NIL, every immediately returns NIL. Otherwise, every computes - 
every fno[everyx], or cdr[everyx] if everyfn2=NIL, and uses this as - 
the "пем" everyx, and (һе process continues, eg. 
every[x; ATOM ; СОРА] is true if every other element of x is atomic. 


every compiles open. 


15 A loose description of equal might be to say that x and y are equal if they print out the same way. 


16 


Actually, КОШТО everyx] is computed, so for example everyfnl can look at the next clement on everyx if 
necessary. 
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some[somex ;somefn1;somefn?2] 


value is the tail. of somex beginning with the first element that 
satisfies somefnl, i.e., for which somefnl applied to that element is | 
true. Маше is NIL if по such element exists. 

e.g., some[x; (LAMBDA (Z) (EQUAL Z Y))] is equivalent to 
member[y;x]. some operates analogously to every. At each stage, 
somcefnl[car[somex]:somex] is computed, and if this is not NIL, 

somex is returned as thc value of some. Otherwise, somefn?2[somex] 
is computed, or шнен if somefn2=NIL, and used for the 


| next somex. 


some comites Open. 


notany[somex; somefnl ,somefn2] 


same as s notfsomefsomex:s somefnl: somefn2] 


notevery[everyx; өнуі; еуегуЁп2] 


memb[x:y] 


fmemb[x;y] 


member[x;y] | 


eqmemb[x;y] 


not[every[everyx; everyfal; everyfn2]] 


Determines if x is a member of the list у, i.e., , if there is an element | 
of y eg to x. И so, its value is the tail of the list y starting with | 
that element. If not, its value i is NIL. 


. Fast version of memb that compiles open as a five instruction loop, 
A terminating on a NULL check. Interpreted, fmemb gives an error, 


BAD ARGUMENT. - FMEMB, if y ends in a а non-list other than 
NIL. ; жə | 


Identical to memb except that it uses c equal instead of € eq to check 
membership Of xi x in y. 


true if either x is eq to y, ог else y is a list. and x is an fmemb of y. 
Compiles open: | 


Тһе reason for the existence of both memb and member is that ед compiles as one instruction but 


equal requires a function call, and is therefore considerably more expensive. Wherever possible, the | 


user should write (and use) functions that use eq instead of equal. | 


tailp[x;y] 


ds x, if x is a tail of y і.е. X is eq to some number of cdrs > 0 of - | 
у, 17 NIL otherwise. — РА 


If x is са to some number of cdrs > 0 of y, we say x is a proper tail. 


512 


assoc[key;alst] 


fassoc[key;alst] 


sassoc[key;alst] 


putassoc[key; val;alst] 


listget[Ist;prop] 


listput[Ist;prop; val] 


listgetl[Ist;prop] 


listputl[Ist;prop; val] 


18 
beginning. 


19 listgetl used to be called get. 
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alst is a list of lists (usually dotted pairs). The value of assoc is the 
first sublist of alst whose car is eq to key. If such a list is not 
found, the value is NIL. Example: | 

asoc[B;((A . 1) (В. 2) (С . 3))] = (В. 2). 


Fast version of assoc that compiles open as а 6 instruction loop, 
terminating on a NULL check. Interpreted, fassoc gives an error if- 
alst ends in a non-list other than NIL, 
BAD ARGUMENT - ҒА550С. | | 


Same as assoc but uses equal instead of eq. 


Searches alst for an element car of which is eq to key. If one is 
found, cdr is replaced (using rplacd) with val. If no such element is 
found, cons[key;val] is added at the end of alst. Value is val. If 
alst is not a list, generates an error, ARG NOT LIST. | 


Similar to getprop (Section 7) but works on lists using property list 


format. Searches Ist two elements at a time, 1.е., by cddr, looking 
for an element eq to prop. If one is found, returns the next 
element of Ist, otherwise NIL. Returns NIL if Ist is not a list. 


Similar to putprop. Searches Ist by cddr looking for an element eq 
to prop. If prop is found, replaces the next element of Ist with val. 
Otherwise, prop and val are added to the end of 151.18 Value is val. 
Generates an ARG NOT LIST error if Ist is not a list. 


Like listget, but searches Ist one cdr at a time, i.e., looks at each 
element. 


Like listput, except searches Ist one cdr at a time. 


If Ist is a list with an odd number of elements, or ends іп a non-list other than NIL, prop and val are added at its | 
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LIST MANIPULATION АМО CONCATENATION 


list[x 1:x5;...:xg] 


append[x; ;x»;...:x] 


nconc[x ЗНА 


lambda-nospread function. Its value is a list of the values of its 
arguments. | 


Copies the top level of the list Xl and appends this to à copy of top 
level list x9 appended to ... appended to x, e.g., 

аррепа(А B) (C D E) (Р G)] = (А B CDEF G). 

Note that only the first n-l lists are copied. However n=1 is 


treated specially; i.e., appendix} can be used to copy the top level of 


a single list. 
The following examples шне the treatment of non-lists. | 


аррелАГ(А В C);D] = (АВС. D) 

append[A; (B C 0)] = (BC D) 

append[ (A B C . 0); (Е F G)] = (ABCEF RU 
append(A В С . 0)] = (АВС. D). 


Returns same ү as append but actually ‘modifies the list 
structure of x1 ... n-L 


Note that nconc cannot change NIL to a list. In other words, if the value of foo is NIL, then the 
value of (NCONC FOO (QUOTE (A B C))) is (A B C), but foo will not have been changed. 
Тһе "problem" is that nconc simply has a collection of pointers to work with, and does not know | 
where they originally came from, i.e., does not know that this NIL is the value of foo, and while it 
is possible to alter list structure using rplaca, there is no way to change a non-list to a list. 


nconcl[Ist;x] 


l 


Performs nconc[lIst;list[x]]. 


To copy a list to all levels, use copy. 
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tconc[ptr;x] 


Iconc[ptr;x] 
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tconc is useful for building a list by adding elements one at a time 
at the end, ie. its role is similar to that of nconcl. However, 
unlike nconcl, tconc does not have to search to the end of the list 
each time it is саПед. It docs this by keeping a pointer to the end 
of the list being assembled, and updating this pointer after each 
call. The savings can be considerable for long lists. The cost is the 
extra word required for storing both the list being assembled, and 
the end of the list. ptr is that word: car[ptr] is the list being 
assembled, cdr[ptr] is last [car[ptr]]. The value of tconc is ptr, with 
the appropriate modifications to car and cdr. Example: 


С(ВРТО 5 (SETQ FOO (TCONC FOO RPTN))) 
((5 43 2 1) 1). 


(сопс сап be initialized in two ways. If ptr is NIL, tconc will make 
up a ptr. In this case, the program must set some variable to the 
value of the first call to tconc. After that, it is unnecessary to reset 
ptr since tconc physically changes it. Thus: | 


Hu FOO (TCONC NIL 1)) 
((1) 1 


` e€(RPTQ 4 (TCONC FOO RPTN)) 


((1.4 3 2 1) 1). 


If ptr is initially (NI L) the value of t tconc is the same as for 
ptr=NIL, but tconc changes ptr, e.g., | 


 e(SETQ FOO (CONS)) 


(NIL) 
-(ВРТО 5 (TCONC FOO RPTN)) 
(ФО 4 3 2 1) 1). 


The latter method allows the program to initialize, and then call 
tconc without having to perform setq on its value. 


Where (сопс is used to add elements at the end of а list, Ісопс is | 
used for building a list by adding lists at the end, i.e., it is similar 
to nconc instead of nconcl, e.g., 


-(SETQ FOO (CONS)) 

(NIL) 

e(LCONC FOO (LIST 1 2)) 
((12) 2) 

-(LCONC FOO (LIST 3 4 5)) 
((1234 5) 5) 

«(LCONC FOO NIL) 

((1 23 4 5) 5) 


Note that 


«(ТСОМС FOO NIL) 

((1 2 3 4 5 NIL) NIL) 

е(тсомс FOO (LIST 3 4 5)) | 

((12 345 NIL (34 5)) (3 4 5)) 
| 6.2 
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Ісопс uses the same pointer conventions as (сопс Юг climinating 
searching to the end of the list, so that the same pointer can be 
given to (сопс and Ісопс interchangeably. 


The functions docollect and endcollect also permit building up lists from left-to-right а la (сопс, 
but without the overhead of the extra cons cell. The list being maintained is kept as а circular list list. 
docollect adds items; enacouce replaces the tail with its second argument, and returns the full list. 


docollect[item;Ist] "adds" Кет (о end of Ist. 
endcollect[Ist; tail] "adds" tail onto end of Ist and returns Ist. 


For example, mapcar is essentially: - 


(LAMBDA (L FN) 
[PROG (VAL) 
LP (COND ((NLISTP L) (RETURN (ENDCOLLECT VAL)))) 
(SETQ VAL (DOCOLLECT (APPLY* FN (CAR L)) VAL)) 
(ФЕТО L (CDR L)) 
(GO LP)] 


attach[x;]] Value is equal to сопзјх: 1], but attaches x to the front of 1 by doing 


ап rplaca and rplacd, i.e., the value of attach is eq to 1, which it- 


physically changes. attach[x;NIL] is the same as cons[x;NIL]. 
Otherwise, if 1 is not a list, an error is а ARG NOT LIST. 


remove[x;]] Removes all occurrences of x from list 1, giving a copy of 1 with all- 
. .. elements equal to x removed. 


Convention: Naming a function by prefixing an existing function with d frequently indicates the 
new function is a destructive version of the old one, i.e, it does not make any new structure but 
cannibalizes its argument(s). | E 


dremovel[x ;1] Similar to remove, but uses eq instead of equal, and actually 
modifies the list > list 1 when removing x, and thus does not use апу 
additional storage. More efficient than remove. 


Note that dremove cannot change a list to NIL. For example, if the value of foo is (A), then 
(DREMOVE (QUOTE A) FOO) will return NIL, and not perform any conses, but the value of foo 


will still Бе (A) because there is not way to change a list to a non-list. Sec discussion following 


description of nconc on page 6.2. 


mklist[x] if x is a list or NIL, value is x. Otherwise, value is list[x]. 
Compiles open. 
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сорујкј јат 22 Makes а сору of the list s The value of copy is the copied list. 
Ша е, All levels of x are copicd,? down to non-lists, so that if x contains 
arrays and strings, the copy of x will contain the same arrays and 
strings, not copies. Copy is recursive in the car direction only, so 

that very long lists can be copied. 


соруа х] . | ЕЕ Like с сору ехсері copies down to atoms, ie. arrays, hash-arrays, 
| | strings, user data types, etc., are all copied.? 


" hcopyall[x] . Like copyall except will work even if data structure contains circular 


+ pointers. 
reverse[l] z Reverses (and copies) the top level of а list, ер, 
B reverse[ (A В (C D))] = ((C D) B A). If1is not a list, value 
is 1. | | 
dreverse[l] ЕА Value is same as that of reverse, but dreverse destroys the original 
list 1 and thus does not use any additional storage. More efficient 
than reverse. | 


. Ssubst[new;old;expr] | Value is the result of substituting the S-expression new for all 
"E occurrences of the S-expression old in the S-expression expr. 
Substitution occurs whenever old is equal to car of some 
subexpression of expr, or when old is both atomic and not NIL and 

eg to cdr of some subexpression of expr. For example: 


subst[A;B; (C B (X. 52)1 = (СА (X . A)) 
subst(A;(B C);((B C) D B C)] = Е. DBC), 
not (A D . А). 


The value of subst is a copy of expr with the appropriate changes. | 
Furthermore, if new is a list, it is copied at each substitution. 


dsubst[new;old;expr] Similar to subst, but does not copy expr, but changes the list 
structure expr itself. Like subst, dsubst substitutes with a copy of 
new. More efficient than subst. 


Isubst[new;old;expr] Like subst except new is substituted as a segment, eg, 
Isubst{((A B); Y;(X Y Z)]is (X A B Z). Note that if new is 
NIL, produces a copy of expr with all old's deleted. 


To copy just the top level of x, do append[x]. 


————— 


compare their ыц а 
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esubst[new ;old;expr;errorflg;charflg] 


sublis[alst;expr;flg] 


dsublis[alst;expr;flg] 


subpair[old;new;expr;flg] 


Similar to dsubst, but first checks to sce if old actually appears in 


expr. Implements the editors R and RC command. More complete 


discussion can be found in Section 9. 


alst is a list of pairs: ((ај . vy) lon’, v5) .. (us . Vp) with each и, 
atomic. Pas 


The value of sublis[alst;expr;flg] is the result of substituting each у 
for the corresponding u in expr, " e.g., | | 
sublis[( (A . X) (С. Y));(A BC D)] = (X ВУ D). 


New structure is created only if needed, or if flg=T, eg., if 


Яе  NIL and there are no substitutions, value is eq to expr. 


Similar to sublis, but does not copy е хрг, but changes the list 


structure expr itself. 


Similar to sublis, except that clemens of new are substituted for 
corresponding at atoms of old in expr, e.g., 

subpair[ (А C);(X Y);(A B C D)] = (X B Y D) 

As with sublis, new structure is created only if needed, or if flg=T, 


e.g., if fla=NIL and there are no substitutions, the value is eq to 


expr. 


If old ends in an atom other than NIL, the rest of the elements on 
new аге substituted for that atom. For example, if 


old=(A B . С) and new=(U V X Y Z), U is substituted for 
A, V for B, and (X Y Z) for C. Similarly, if old itself is an atom - 


(other than NIL), the entire list new is substituted for it. 


Note that subst, dsubst, Isubst, and esubst all substitute copies of the appropriate expression, 
whereas subpair and sublis substitute the identical structure (unless flg = T). 


last[x] 


flast[x] 


пећ па! 


Value is a pointer to the last node in the list x, e.g, ifx=(A B С) 
then last{x] = (C). Их- (АВ. С) lastik] = (В. С). Value 
is NIL if x is not a list. | 


Fast version of last that compiles open as а 5 instruction loop, 
terminating on a null-check. Interpreted, generates an error, 
BAD ARGUMENT - FLAST, if x ends in other than NIL. | 


Тай is а tail of 1 or NIL. The value of nleft is the tail of 1 that 


To remember the order оп alst, think of it as old to new, i.e., Uic > MI 
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++ 


lastn[l;n] 


nth[x;n] 


| fnth[x;n] | 


“Тепе |! 


· flength[x] 


+ + + + 


count[x] © 


eglength[x;n] | 
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contains n more elements — than tail? eg. if 
x=(A B C D E), ме х:2]=(0 E), 

nlefi[x;l;cddr[x]]| 2 (B СО E). Thus пей can be used to work 
backwards through a list. Value is NIL if 1 does not contain n 
more elements than tail. 


Value is cons[x;y], where y is the last n elements of 1, and x is the 
initial segment, е, — — 

lastn[ (A B C D E);2]-((A B C) D E) 

lastn[ (A B);2]=(NIL A B). 


Value is NIL, if 1 is not a list containing at least n elements. 


Value is the tail of x beginning with the ntthelement, e.g., if n=2, 
value is сак), if n=3, cddr[x], etc. If n— 1, value is x, if n=0, for 
consistency, value is cons[NIL;x]. If x has fewer than n elements, 
value is NIL, ер, nth[(A B);3]=NIL, as is MA . B);3] 
Note that pap А В); 2]*B. 


Fast don of nth that compiles open as a 3 instruction loop, 
terminating on a null-check. Interpreted, generates an error, 
BAD ARGUMENT - FNTH, if x ends in other than NIL. 


Value is the length of the. list x where length | is defined as the 
number of саго required to reach а non-list, e.g., | 


length[ (A B C)] = 3 | 
length[(A B C . D)] - 3 
length[A] = 0 


Fast version of length that compiles open as a 4 instruction loop, 
terminating on а null-check. Interpreted, generates an error, 
BAD ARGUMENT - FLENGTH, if x ends in other than NIL. 


equivalent to equal[length[x]:;n], but more efficient, i.e. eglength 


stops as soon as it knows that x is longer than n. Note that 
eglength is also safe to use on (possibly) circular lists, since it is- 
"bounded" by п. | 


Value is the number of list words in the structure x. Thus, count is 
like a length that gocs to all levels. Count of a non-list is 0. 


If tail is not NIL, but not a tail of 1, the result is the same as if tail were NIL, i.e., шеП operates by scanning 1 


looking for tail, not by computing the lengths of ] and tail. 


келын Пт кин ннан ШЫ edis е 
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countdown[x;n] Counts number of list words in x, decrementing n for each one. 
Stops when it finishes counting x, or when n reaches 0. Value is the © 
current n. In other words, the value of countdown is the larger of 0 
and idifference[n;count[x]], but countdown is more efficent, and can 
be used. on circular structures since it is "bounded" by n. Note 
that countdown is to count what equaln (Scction 5) is to equal. 


++++++ 


а Ах; у; 2] . y must be a tail of x, 1.е., eq to the result of applying some number 
| Of cdrs to х. Idifflx:y] gives а list of all elements in x up to y, i.e., 
the list difference of x and у. Thus ldiff[x; member[F00; à gives all 
elements in x up to the first 200, 


Note that the value of Idiff is always new list structure unless у= NIL, in which case the value is x 
itself. 


If z is not NIL, the value of Idiff is effectively nconc[z;ldifi[x;y]], 
1е., the list difference is added at the end of z. | 
ІҒу is not а tail of x, d an error, LDIFF: NOT A TAIL. 


diff terminates on a null-check. 


Idifference[a;b] list difference. Value is list ot those elements in a that are not 
members of b. 


+ + 


intersection[x;y] Value is a list whose elements are members of both lists х and у. 
| Note that intersection[x;x] gives а list of ай members of x without 
any duplications. 


union[x;y] ши Value is а (new) list consisting of all elements included on either of 
the ENG original lists. It is more efficient to make x be the shorter 
1156.6 | 


sort[data;comparefn]' data is a list of items to be sorted using comparefn, a predicate 
function of two arguments which can compare any two items on 
data and return T if the first one belongs before the second. If 
comparefn is NIL, alphorder is used; thus sort[data] will 
alphabetize а list. If comparefn is T, car's of items that are lists are 
given to alphorder, otherwise the items themselves; thus 


The value of union is y with all elements of x not in y consed on the front of it. Therefore, if an element appears 
twice in y, it will appear twice іп  union[x;y]. Also, since union[(A);(A A)] = (A A), while 
union[(A А); (A)] = (A), union is non-commutative. | 


sort was written by L. P. Deutsch. 


6.7 


Note: if comparefn[a;b] = 


preserved. 


For example, if (FOO . 
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ки -list;T] will alphabetize an assoc list by the car of each item. 
On TEES? will sort a list of integers. | 


The yide of sort is the sorted list. The sort is destructive and uses 


no extra storage. The value returned is eq to data but elements 
have been switched around. Interrupting with control D, E, or B 
may cause loss of data, but control H may be used at any time, and 
sort will break at a clean state from which t or control characters 
are safe. The algorithm used by sort is such that the maximum 
number of compares is n*logy n, where n is length[data]. 


comparefn[b;a], then the ordering of a and b may or may not be. 


ЕТЕ) appears before (FOO . FUM) in x, sort[x; T] may or may not 


reverse the order of these two elements. Of course, the user can always specify a more precise 


comparefn. 


merge[a;b;comparefn] 


alphorder[a;b] 


a and b are lists which have previously been sorted using sort and 
comparefn. Value is a destructive merging of the two lists. It does 
not matter which list is longer. After merging both a and b are © 


equal to the merged list. (In fact, Sa 15 E to cdr[b]). m merge may 


be aborted after control- H. 


А predicate function of two arguments, for alphabetizing. Returns 
T if its arguments are in order, i.e., if b does not belong before а. 
Numbers come before literal atoms, and are ordered by magnitude 
(using greaterp) Literal atoms and strings are ordered by 
comparing the (ASCII) character codes in their pnames. Thus 


.alphorder[23;123] is T, whereas alphorder[A23;A123] is NIL, 
because the character code for the digit 2 is greater than the code 


for 1. 


Atoms and strings are ordered before all other data types. If 
neither a nor b are atoms or strings, the value of alphorder is T, 


те. in order. 


Note: alphorder does no unpacks, chcons, conses or nthchars It is several times faster for 
alphabetizing than anything that can be written using these other functions. 


mergeinsert[new;lst;oncflg] 


фа 


Ist is NIL ог a list of partially sorted items. mergceinsert tries. to 
find the "best" place to (destructively) insert new, eg. 
mergeinsert[FIE2; (FOO FOO1 ЕТЕ FUM)]= | 
(FOO F001 ЕТЕ FIE2 FUM). Value is Ist. mergeinsert is 
undoable. 


If oncflg=T and new is already а member of Ist, mergeinsert does 
nothing and returns ns Ist. | | 
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mergeinsert is used by addtofile (Section 14) to insert the name of a new function into a list of 
functions. The algorithm is essentially to look for the item with the longest common leading 
. sequence of characters with respect to new, and then merge new in starting at that point. 


comparelists[x;y] compares x and у and prints their differences, ie. comparelists is + 
essentially a SRCCOM for list structures. | | + 
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SECTION 7 
PROPERTY LISTS AND HASH LINKS 


7.1 PROPERTY LISTS 


Property lists are entities associated with literal atoms. Property lists are conventionally lists of the 
form (property value property value ... property value) although the user can store anything he 
wishes in the property list of a literal atom. However, the functions. which manipulate property 
lists observe this convention by cycling down the property lists two сат at a time. Most of these 
functions also generate an error, ARG NOT LITATOM, if given ап argument which is not a literal 
atom, ќе, they cannot be used directly on lists. 


The term "property name" or "property" is used for the property indicators appearing in the odd 
positions, and the term "property value" or "value of a property" or simply "value" for the values 
appearing. in the even positions. Sometimes the phrase "to store on the property --" is used, 

meaning (о place the indicated information on the property list under the property name --. | 


Properties are usually. atoms, although no checks are made to mma use ој non-atoms тап 
odd position. However, the property list searching functions all use eq. 


PROPERTY LIST FUNCTIONS 


getproplist[atm] if atm is a literal atom, returns property list of atm. Otherwise, 
generates ARG NOT LITATOM error. In Interlisp-10, getproplist 
compiles open without any error checks. | | 


setproplist[atm;lst] if atm is a non-NIL literal atom, sets property list of atm to be Ist, 
and returns Ist as its value. If atm is NIL, generates an ATTEMPT _ 
TO RPLAC NIL (unless Ist is also NIL). If atm is not a literal — 
atom, generates an ARG NOT LITATOM error. | 


getprop[atm;prop]! gets the property value for prop from the property list of atm. The- 
valuc of gctprop is NIL if atm is not a literal atom, or г ргор is not 
found. | | 

1 


getprop used to be called getp. 
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putprop[atm:prop;val] 


era d 


saveput[atm;prop;val] 


++ 


addprop[atm;prop;new;flg] | 


| remprop[atm;prop] 
+ remproplist[atm;props] 


VET in а Section 5. 
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Note: the jale of getprop may also be NIL, if there is an occurrence of prop but the 
corresponding property value is NIL. The only way to distinguish these two cases is to perform : 


memb[prop; getproplist{atm]]. 


Note: Since getprop searches a list two items at a time, the same _ 
object can be used as both a property name and a property value, 
e.g., if the property list of atm is (PROP1 A PROP2 В А С), 


then getprop[atm;A] = С 


puts on the property list of atm,” the property prop with value val. 


val replaces any previous value for the property prop on this 
property list. Generates an error, ARG NOT LITATOM, if atm 5 . 
not a literal atom. Value is val. | 


олш а а „propp; vall 


nlambda nospread version of putprop. For i—l..n, puts ргор;, 
value val; on property list of atm. Performs some file package (see 
Section 14) related operations, i.e. "notices" that the corresponding 
properties have been changed. Used by for implementing various 


file package commands. 


same as put, but sis the TOETA property value as риш 


бееп а (for the file package, Section. 14). | 


adds the value new to the list which is the value of property prop 


on property list of atm. If flg is T, new is consed onto the front of 


value of prop, otherwise it is nconced on the end (nconcl) If atm 


does not have a property prop, the effect is the same as 


putprop[atm:;prop:list[new ]], г example, if 
addprop[F00;PROP;FIE] 15 = followed by 
addprop[ FOO; PROP; FUM], getprop[FOO;PROP] | will 


Бе (ЕТЕ FUM). The value of addprop is the (new) property value. 
If atm is not a literal atom, generates an error, ARG NOT 


LI TATOM. 


removes all occurrences of the property prop (and its value) from 
the property list of atm. Value is prop if any were found, otherwise 
NIL. If atm is not а literal atom, generates ап error, 
ARG МОТ LITATOM. 


removes all occurrences of all propertics on props and their | 
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corresponding property values from property list of atm. Value 15 
NIL. | 


changepropl[x:propl;prop2] Changes name of property propl to prop2 on property list of x, 
E (but does not affect the value of the property). Value is x, unless 

propl is not found, in which case, the value is NIL. If x is not a 

literal atom, generates an error, ARG NOT LITATOM. | | 


propnames[atm] value is a list of the property names on the property list of atm. 


gctlis[x;props] searches the property list of x, and returns the property list as of 
| | the first property on props that it finds с.р., if the property list of x 
is (PROP1 A PROP3 BAC); | 
getlis[x;(PROP2 PROP3)]=(PROP3 B A С) | 
Value is NIL if no clement on props is found. x сап also be. a ist 
itself, in which case it is searched as above. 


deflist[l;prop] is used to put values under Ше same property name on the 
Е property lists of several atoms. 1 is а list of two-element lists. The - 


first element of each is a literal atom, and the second element is the 
property value for the property prop. The value of deflist is NIL. 


Note: Many atoms in the system already have property lists, with properties used by the compiler, 
the break package, DWIM, etc. Be careful not to clobber such system properties. The value of 
sysprops gives the complete list of the property names used by the system, | 


7.2 HASH LINKS 


The description of the hash link facility in Interlisp is included in the chapter on property lists 
because of the similarities in the ways the two features are used. A property list provides a way of 
associating information with a particular atom. A hash link is an association between any Interlisp 
pointer (atoms, numbers, arrays, strings, lists, et al) called the hash-item, and any other Interlisp 
pointer called the hash-value. Hash links are implemented by computing an address, called the 
hash-address, in a specified array, called the hash-array, and storing the hash-value and Ше 
hash-item into the cell with that address. The contents of that cell, ie. the hash-value and 
hash-item, is then called the hash-link.? | 


Since the hash-array is obviously much smaller than the total number of possible hash-items,^ the 


The term hash link (unhyphenated) refers to the process of associating information this way, or the “association” as 
an abstract concept. 


which is the total number of Interlisp pointers, i.e. in Interlisp-10, 256K. 


7.3 


+ 
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hash-address computed from item may already contain a hash-link. If this link is from item,” the 
new hash-value simply replaces the old hash-value. Otherwise, another hash-address (in “the same 
hash-array) must be computed, etc, until an empty cell is found,® or a cell containing a hash-link 
пош item. : | 


When a hash link for item is beine retrieved, the hash-address is computed using the same 
algorithm as that employed ed for making the hash link. If the corresponding cell is empty, there is 
no hash link for item. If it contains a hash-link from item, the hash-value is returned. Otherwise, 
another hash-address must be computed, and so forth. 


. Note that more than one hash link can be associated with a given hash- -цет by using. more than. 
опе ћазћ-агтау. | | 


| HASH LINK FUNCTIONS 


In the ‘description of the functions below, the argument array has one of, three forms: [1] NIL, in 
which case the hash-array provided by the system, syshasharray, is used;’ [2] a hash-array created 
by the function harray; or [3] a list car of which is a hash-array. The latter form is used for 
specifying what is to be done on overflow, as described below. 


harray[n] ИУ creates а  hash-array of size at least nê equivalent to 
; | i : cIrhash[array[n]]. | 
harrayp[x] | e is x, if x is a hash array. 

harraysize{harray] ии ЖТ size of harray. 

clrhash{harray] | clears all hash links of harray. Value is harray. 

puthash[item;val;harray] © puts into harray a hash-link кой item to val. Replaces previous 


link from same item, if any. If val=NIL any old link is removed, 
(hence a hash-value of NIL is not allowed). Value is val. 


gethash[item;harray] finds hash-link from item in harray, and returns the hash-value. 
i Value is NIL, if no link exists. gethash compiles open. | 


5 eq is used for ашар item with the hash-item in the cell. 

6 When the hash array becomes 7/8 full, it is considered to be full, and the array is either ашы or ап еггог is 
generated, as described below in the discussion of overflow. 

7 syshasharray is not used by the system, it is provided solely for the user's benefit. It is initially 512 words large, and 
is automatically enlarged by 50% whenever it is "full". Sce page 7.5. 
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In Interlisp-10, the size of the hash array may be increased so that it is relatively prime to possible probe intervals. 
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rehash[oldar;newar] hashes all items and values in oldar into newar. The two arrays do 
| not have to be (and usually aren't) the same size. Value is newar. 


maphash[array;maphfn] maphfn is a function of two arguments. For each hash-link in 
| array, maphfn will be applied to the hash-value апа hash-item, e.g. 
maphash[a;(LAMBDA (X Y) (AND (LISTP Y) (PRINT X)))] 
will print the hash-value for all Tam links from lists. The value of 

maphash is array. 


dmphash{arrayname, ;arrayname),...;arrayname, | 
Nlambda-nospread that prints on : the primary output file loadable 
forms which will restore what is in the hash-array specified by 
arrayname;, ер. (E (DMPHASH SYSHASHARRAY)) as a file 
package command will oe the system hash-array. 


Note: all eq identities except atoms and small integers are Jo dumping and loading because 
read will create new structure for each item. Thus if two lists contain ап eq substructure, when 
И are dumped and loaded back in, the corresponding substructures while equal are no longer 


HASH OVERFLOW 


By using an array argument of a special form, the user can provide for automatic enlargement of a . 


hash-array when it overflows, i.e., is full and an attempt is made to store a hash link into it. The 
array argument is either of the form [1] (hash-array . n), n a positive integer; [2] (hash-array . f), f 
a floating point number; [3] (hash-array); ог [4] (hash-array . fn), fn a function name or a lambda 
expression. In the first case, a new hash-array is created with n more cells than the current 
hash-array. In the second case, the new hash array will be f times the size of the current 


hash-array. The third case, (hash-array), is equivalent to (hash-array . 1.5). In the fourth case, 


(hash-array . fn), fn is called with (hash-array . fn) as its argument. If fn returns a number, the 
number will be the size of the new hash array. Otherwise, the new size defaults to 1.5 times the 
size of the old hash array, e.g. fn could be used to print a message, or perform some monitor 
function. In each case, the new hash-array is rplacaed into the dotted pair, and the computation 
continues. | 


If a hash-array overflows, and the array argument used was not one of these three forms, the error 
HASH TABLE FULL is generated, which will either cause a break or unwind to the last errorset, as 
per treatment of errors described in Section 16. 


The system hash array, syshasharray, is automatically enlarged by 1.5 when it is full. 


The HORRIBLEVARS prettydef command (Section 14) provides а way of dumping hash tables such that these 
identities are preserved. 
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SECTION 8 
FUNCTION DEFINITION AND EVALUATION 


GENERAL COMMENTS 


A function definition in Interlisp is stored in a special cell called the function definition cell, which 
is associated with each literal atom. ‘This cell is directly accessible via the two functions putd, 
which puts a definition in the cell, and getd which gets the definition from the cell. In addition, 
the function fntyp returns the function type, ie, EXPR, EXPR* ... FSUBR* as described in 
section 4. Exprp, ccodep, and subrp are true if the function is an expr, compiled function, or subr 
respectively; argtype returns 0, 1, 2, ог 3, depending on whether the function 15 a spread or 
nospread (е. its fntyp ends іп *), or evaluate or no-evaluate (i.e., its fntyp begins with Е or CF); 
arglist returns the list of arguments; and nargs returns the number of arguments. fntyp, exprp, 
ссодер, subrp, argtype, arglist, and nargs can be given either a literal atom, in which case they 
obtain the function definition from the atom’s definition cell, or a function definition itself. 


SUBRS 


Because subrs! are called in a special way, their definitions are stored differently than those of - 
compiled or interpreted functions. getd of a subr returns a dotted pair, car of which is an 
encoding of the argtype and number of arguments of the subr, and cdr of which is the address of 
the first instruction. Note that each getd of a subr performs а cons. Similarly, putd of a definition 
of the form (number . address), where number and address are in the appropriate ranges, stores the 
definition as a subr. 


VALIDITY OF DEFINITIONS IN INTERLISP-10 _ 


Although the function definition cell is intended for function definitions, putd and getd do not 
make thorough checks on the validity of definitions that "look like" exprs, compiled code, or subrs. 
Thus if putd is given an array pointer, it treats it as compiled code, and simply stores the array 
pointer in the definition cell. getd will then return the array pointer. Similarly, a call to that 
function will simply transfer to what would normally be the entry point for the function, and 
produce random results if the array were not compiled function. 


Basic functions, handcoded in machine language, е.р., cons, car, cond. The terms subr includes spread/nospread, 
eval/nocval functions, i.e., the four fntyps SUBR, FSUBR, SUBR*, and FSUBR*., | 
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Similarly, if putd is given a dotted pair of the form (number . address) where number and address 
fall in the subr range, putd assumes it is a subr and stores it away as described earlier. getd would 
then return a dotted pair equal (but not eq) to the expression originally given putd. Similarly, a 
call to this function would transfer to the corresponding address. 


Finally, if putd is given any other list, it simply stores it away. A call to this function would then 
go through the interpreter as described in the appendix. | 


Note that putd does not actually check to see if the s-expression is valid definition, 1.е., begins with 
LAMBDA or NLAMBDA. Similarly, exprp is true # а definition is a list and not of. the form- 
(number . address), number — 0, 1, 2, or 3 and address a subr address; s subrp is true if it is of this 
form. arglist and nargs work correspondingly. | | 


. Only fntyp and argtype check function definitions further than that described above: both argtype 


and fntyp return NIL when exprp is true but car of the definition is not LAMBDA or NLAMBDA .: 
In other words, if the user uses putd to put (A B C) in a function definition cell, getd will return 
this value, the editor and prettyprint will both treat it as a definition, e екрір will return Т, ccodep 
aS subrp | NIL, arglist В, and nargs 1. 


getd[x] gets the function definition of x. Value is the definition.3 Value is 


NIL if x is nota literal atom, or has no definition. 


fgetd[x] fast version of getd that compiles open. Interpreted, generates an 
| | error, BAD ARGUMENT - FGETD, if x is not a literal atom. Fgetd 
is intended primarily to check whether a function has a definition, 
rather than to obtain the definition. Therefore, for subrs, fgetd 
returns just the address of the function definition, not the dotted 

pair returned by getd, page 8.1, thereby saving the cons. 


putd[fn;def] | puts the definition def into Б fünction cell. Value is def 

зи | Generates an error, ARG МОТ LITATOM, if fn is not a literal atom. 
Generates an error, ILLEGAL ARG, if def is a string, number, or 
literal atom other than NIL. | 


. putdq[fn;def] nlambda version of putd; both arguments are considered quoted. 


Value is fn. 
putdq?[fn;def] = nlambda version of рша. If fn is not defined, same as putd[fn;def]. 


Otherwise, does nothing and returns NIL. 


2 These functions have different values on LAMBDAs and NLAMBDAs and hence must check. The compiler and 
interpreter also take different actions for LAMBDAs and NLAMBDAs, and therefore generate errors if the definition is 
neither, 


3 Note that in Interlisp-10, getd of a subr performs a cons, as described on page 8.1, 
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movd|from;to;copyflg] 


movd?[from;to;copyflg] | 


Moves the definition of from to to, i.e., 


if to is not defined, same as movd[from;to;copyflg]. 
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redefines to. If 
copyflg=T, а copy of the definition of from is used. copyflg=T is 


only meaningful for exprs, although movd works for compiled 


functions and subrs as well. The value of movd is to. 


Otherwise, 
does nothing and returns NIL. - 


Note: јтур, subrp, ccodep, m ep. exp rp, argtype, nargs, and arglist all can be given either the 
name of a function, or a definition. 


fntyp[fn] 


subrp[fn] 
ccodep[fn] 


scodep[fn] 


exprp[fn] 


argtype[fn] 


Value is NIL if fn is not a function definition or the name of a 
defined function. Otherwise fntyp returns one of the following as 
defined in the section on function types: 


EXPR CEXPR SUBR 

FEXPR CFEXPR FSUBR 

EXPR* CEXPR* SUBR* 
 FEXPR* CFEXPR*  FSUBR* . 


The prefix F indicates unevaluated arguments, the prefix С indicates 
compiled code, and the suffix * indicates an indefinite number of 
arguments. | 


fntyp returns FUNARG if fn is a funarg expression. Sce Section 11. 


is true if and only if fntyp[fn] is either SUBR, FSUBR, SUBR*, or 
FSUBR* , i.e., the third column of fntyp's. | 


is true if and only if — | is either CEXPR, 


CFEXPR, 
CEXPR*, or СЕЕХРА“, 1.е., second column of fntyp's. | 


is true if fn has or is a swapped compiled definition (see Section 3). 


is true if fntyp[fn] is cither EXPR, FEXPR, EXPR*, or FEXPR*, 
i.e., first column of fntyp's. However, exprp[fn] is also true if fn is 
(has) a list definition that is not a SUBR, but docs not begin with 


++ 


cither LAMBDA ог NLAMBDA. In other words, с exprp is not quite as- 


selective as fntyp. 


fn is the name of a function or its definition. The value of argtype 
is the argtype of fn, 1.с., 0, 1, 2, or 3, or NIL if fn is not a function. 
The interpretation of the argtype 1s: 

0 cval/sprcad function (EXPR, CEXPR, ЗИВК) 
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. - nargs[fn] 


arglist[fn] | 
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1 no-eval/spread functions ( FEXPR, CFEXPR, FSUBR) 


2 eval/nospread functions (EXPR* , CEXPR*, SUBR*) 
3 no-eval/nospread functions ( FEXPR* ,CFEXPR*,FSUBR*) 


i.e., argtype corresponds to the rows of fntyps. 


value is the number of arguments of fn, or NIL if fn is not a 
function.^ ^ nargs uses ехргр, not мур, so that 
nargs[((A (B C) D)]22. If fn is a nospread function, the value of 
nargs is 1. 


value is the "argument list" for fn. Note that the "argument list" is 
an atom for nospread functions. Since NIL is a possible value for 
arglist, an error is E ARGS NOT AVAILABLE, if fn is not 
a function? 


If fn is a SUBR or FSUBR in Interlisp- -10, the value of a arglist is (U), (U V), (U V W), ек. 
.-. depending on the number of arguments, if a SUBR* or FSUBR*, the value is U. This is merely а 
"feature" of arglist, subrs do not actually store the names of their arguments(s) on the stack. 


smartarglist[fn;explainflg;tail]- 


+ + + + 


If explainflZ=T and fn is а nospread function, e.g., list, selectq, etc., 
smartarglist uses helpsys to interrogate the Interlisp manual to 
obtain more descriptive argument names, e.g., 
smartarglist[SELECTQ; T]-(X Y1 Y2 ... YN 7). If fn is a 
nospread function, and explainflg =NIL, then smartarglist returns 
arglist[fn]. | 


If fn is a spread SUBR, regardless of the value of скрап, 
smartarglist also consults the manual, e.g., 

smartarglist[ READ]- (FILE RDTBL FLG), 

smartarglist[ STKPOS J=(FN N POS). 


For all other cases, and when helpsys is undefined or unsuccessful 
in finding the arguments, smartarglist simply returns arglist[fn]. 


smartarglist first calls fncheck (Section 17) on fn. fncheck will 


i.e., if exprp, ccodep, and subrp are all NIL. 


ТЕ fn is a compiled function, the argument list is constructed, i.e., each call to arglist requires making a new list. For 


interpreted functions, whose definitions are lists of the form (LAMBDA --) ог (NLAMBDA --), the argument list is 


. simply cadr of getd. 


If fn has a list definition, and car of the definition is not LAMBDA or NLAMBDA, arglist will 


check to see if car of the definition is a member of lambdasplst (see Section 17). If it is, arglist presumes this is а 
function object the user is defining via an appropriate dwimuserform (Section 17), and simply returns cadr of the def 
as its argument list. Otherwise arglist generates an error as described above, 
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attempt spelling correction if fn is not the name of a function.® If 
unsuccessful, an error will be generated, fn NOT A FUNCTION, 


| smartarglist is used by break (Section 15) and advise (Section 19) with explainflg=NIL for 
constructing equivalent EXPR definitions, and by the ?= lispxmacro (Section 22), with 
explainflg=T. In order to avoid repeated calls to helpsys, and also to provide the user with an 


override, smartarglist stores the arguments returned from helpsys on the property list of fn under 


the property ARGNAMES and checks for this property before calling helpsys.' 


define[x;-] The argument of define is a list. Each element of the list is itself a 
list either of the form (name definition) Or (name arguments ..). In 
the second case, following "arguments" is the body of the 


definition. As an example, consider the following two чие | 


expressions for defining the function null. 
1) (NULL (LAMBDA (X) (EQ X NIL))) 
2) (NULL (X) (EQ X NIL)) 


define will generate an error, INCORRECT DEFINING FORM, on encountering an atom where a 
defining list is expected. If dfnflg=NIL, an attempt to redefine a function fn will cause define to 
print the message (fn REDEFINED) and to save the old definition of мъ using savedef before 
redefining it. If dfnflg- T, the function is simply redefined. If dfnflg=PROP or ALLPROP, the 
new definition is stored on the property list under the property EXPR. (ALLPROP affects the 
operation of града and град, Section 5). dfnflg is initially NIL. 


dfnflg is reset by load to enable various ways of handling the defining of functions and setting of 
variables when loading a file. For most applications, the user will not reset dfnflg directly himself. 


Note: define will operate correctly if the function is already defined and broken, advised or 
broken-in. 


defineg[x :x;;...:X)] nlambda nospread version of define, і.е., takes an indefinite number 
of arguments which are not evaluated. Each x; must be a list, of 
the form described in define. defineg calls define, so dfnflg affects 
its орсгапоп the same as as define. 


6 tail is used for the call to fixspell. 

7 For spread functions, the argument list itself is stored. For nospread, the form is (NIL arglistl . arglist2) where 
arglistl is the value of smartarglist when cxplainflg— T, and arglist2 the value when explainflg=NIL, e.g. 
gclp[SELECTQ;ARGNAMES]=(NIL (X CLAUSE1 CLAUSE2 ... CLAUSEN DEFAULT) . SELCQ). 

8 except if the old and new definitions are the same, i.e. equal, the effect is simply a no-op. 

9 


For expressions involving type-in only, if the time stamp facility is enabled (Section 9), both define and dcfineq will 
stamp the definition with the user's initials and date. 
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| .. savedef[fn]? 


eval[x] 12 


10 


+ + + + + 


above. 
11 


12 


ипзамеде еа:ргор] | 


Section 8: Function Definition and Evaluation 


Saves the definition of fn on its property list under property EXPR, 
CODE, or SUBR depending on its fntyp. Value is the property 
name used. If getd[fn] is non-NIL, but fntyp[fn] is NIL, saves оп 
property name LIST. This situation can arise when a function is 
redefined which was originally defined with LAMBDA misspelled or 
omitted. 


If fn is a list, savedef operates on each function in the list, and its 
value is a list of the individual values. 


Restores the definition of fn from its property list under property 
prop (see savedef above). Value is prop. If nothing saved under 
prop, and fn is defined, returns (prop NOT FOUND), otherwise 
generates an error, NOT A FUNCTION, 


If prop is not given, ie, NIL, unsavedef looks under EXPR, 
CODE, and SUBR, in that order. The value of unsavedef is the 
property name, or if nothing is found and fn is a function, the 
value is (NOTHING FOUND); otherwise generates an error, NOT A 
FUNCTION. 


If dfnflg=NIL, the current definition of fn, if any, is saved using 
savedef. Thus one can use unsavedef to switch back and forth 
between two definitions of the same function, keeping one on its 
property list and the other in the function definition cell. 


If fn is a list, unsavedef operates on each function of the list, and 


its value is a list of the individual values. 


~ 
 eval evaluates the expression x and returns this value Те. eval 


provides a way of calling the interpreter. Note that eval is itself a 


lambda type function, so its argument is first evaluated, e.g., 


Note: both savedef and unsavedef are redefined in more general terms in Section 14 to operate on typed definitions 
of which a function definition is but one example. Thus, their actual argument lists in Interlisp are different than 
given here: savedef is a function of three arguments, name, type, and definition, and unsavedef a function of two 
arguments, name and type. However, when their extra arguments are defaultcd to NIL, they operate as described 


Sce previous footnote to savedef. 


In Interlisp-10, eval is a subr so that the "name" x does not actually appcar on the stack. 
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boundp[var] 


defeval[type;fn] 


apply[fn;args] 


13 
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-SET(FOO (ADD1 3)) 
(ADD1 3) 

«(EVAL FOO) 

4 


-EVAL(FOO) ог (EVAL (QUOTE ЕОО)) 
(ADD1 3) 


returns T if var is bound in the current context (even if bound to 
NOBIND), or if var has a top level value other than NOBIND. In 
other words, eval[x], where x is an atom, will cause an error, i.e. a 


call to faulteval (Section 16), if and only if the value of boundplx] is. 


NIL. 


specifies how a datum of a particular type is to be evaluated. 
Intended primarily for user defined data types, but works for all 
data types except lists, literal atoms, and numbers. type is a type 
name or type number. fn is a function object, ie. name of a 
function or a lambda expression. Whenever the interpreter 
encounters a datum of the indicated type, fn is applied to the 
datum and its value returned as the result of the evaluation. The 
value of defeval is the previous evaling fn. If fn=NIL, defeval 
returns current. evaling fn without changing it. If fn=T, sets 
evaling function back to system default (which for all data types 
except lists is to return the datum itself). 


apply applies the function fn to the arguments args. The individual 
elements of args are not evaluated by apply, fn is simply called with 
args as its argument list. 14 Thus for the purposes of a apply, 
nlambda's and lambda's are # Ше same. However like eval, 
apply is a lambda function so its arguments are evaluated before i it 
is called e.g., 


compiletypelst (Section 18) permits the user to specify how a datum of a particular type is to be compiled. 


Note that fn may still explicitly evaluate one or more of its arguments itself, as іп the case of setq. Thus, 


(APPLY (QUOTE SETQ) (QUOTE (FOO (ADD1 3)))) will set FOO to 4, whereas 
(APPLY (QUOTE SET) (QUOTE (FOO (А001 3)))) will sct FOO to the expression (ADD1 3). | 
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«5ЕТ(Ғ001 3) 
3 
-SET(FOO2 4) 
4 


«(APPLY (QUOTE IPLUS) (LIST F001 F002] 
| 


Неге, fool and foo2 were evaluated when the зесопд argument to 
apply was evaluated. Compare with: 


-SET(FOO1 (ADD1 2)) 
(ADD1 2) 
<5ЕТ(Ғ002 (5081 5)) 
(SUB1 5) | 
«(APPLY (QUOTE IPLUS) (LIST F001 F002] 


С NON-NUMERIC ARG 
(ADD1 2) 


apply*[fn;arg;;argó;..;argg] ^ equivalent to apply[fn;list[arg;;argo;..;argQ]] For example, if fn is 
. the name of a functional argument to be applied to x and y, one 
| can write (APPLY* FN X Y), which is equivalent to- 
(APPLY FN (LIST X Y)). Note that (FN X Y) specifies a сай | 
to the function FN itself, and will cause an error if FN is not 
defined. (See Section 16.) FN will not be evaluated. 


evala[x;a] Simulates a-list evaluation as in LISP 1.5. x is a form, a is a list of 
| | dotted pairs of variable name and value. a is "spread" on the 
stack, and then x is evaluated, i.e., any variables appearing free in x, 
that also appears as car of an element of a will be given the value 
in the cdr of that element. 


rpt{rptn;rptf] Evaluates the expression rptf rptn times. At any point, rptn is the 
| number of evaluations yet to take place. Returns the value of the 
last evaluation. If rptn < 0, rptf is not evaluated, and the value of 

Iptis NIL. 


Note: трг is a lambda function, so both its arguments are evaluated before трі is called. For most 
applications, the user will probably want to use трга. 


rptq[n;form, ;form,;...;form,] nlambda, nospread version of rpt: n is evaluated, form; are not, 
ер. (RPTQ 10 (READ)) will perform ten calls to read. гри 


compiles open. 


+ frptq{n;form,;form);...;form,] fast version of rptq that compiles open using an assemble macro, 
Docs not bind n. 
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arg[var;m] 


setarg[var;m;x] 


15 
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Used to access the individual arguments of a lambda nospread 
function. arg is an nlambda function used like set. var is the name 
of the atomic argument list to a lambda-nospread function, and is 
not evaluated; m is the number of the desired argument, and is 


evaluated. For example, consider the following definition of 1 iplus 


in terms of plus. 


[LAMBDA X 
- (PROG ((M 0) 
| (N 0)) 
LP (COND 
((EQNX) .. 
(RETURN M))) 
(SETQ М (ADD1 N)) 
[SETQ M (PLUS М (ARG X N))) 
(GO LP] 


The value of arg is undefined for m less than or equal to 0 or 
greater than the value of var. 15 Lower numbered arguments 


appear earlier in the form, e.g., for (IPLUS A B e ; 
arg[X;1]=the value of A, 

arg[X;2]=the value of B, and 

arg[ X; 3] = the value of C. 


Note that the lambda variable should never be reset. However, | 


individual arguments сап be reset using setarg described below. | 


arg compiles open if var is bound locally in the function in which 


the call to arg appears. Otherwise, arg compiles closed and evaluates 
its first argument on each call. Note that this means that the value 


of var must be a SPECVAR. 


sets to x the mth argument for the lambda nospread function whose 


argument list is var. var is considered quoted, m and x are 


evaluated; ер. in the previous | example, 
(SETARG X (ADD1 N)(MINUS M)) would be an i a of the 
correct form for setarg. 


For lambda nospread functions, the lambda variable is bound to the number of arguments actually given to the 


function. See Section 4. 
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SECTION 9 
THE INTERLISP EDITOR! 


The Interlisp editor allows rapid, convenient modification of list structures. Most often it is used to 
edit function definitions, (often while the function itself is running) via the function editf, e.g., 
EDITF(FOO). However, the editor can also be used to edit the value of a variable, via editv, to 
edit a property list, via editp, or to edit an arbitrary expression, via edite. It is an important 
feature which allows good on-line interaction in the Interlisp system. 

This chapter begins with a lengthy introduction intended for the new user. The reference portion | 
begins on page 9.10. 


9.1 INTRODUCTION 
Let us introduce some of the basic editor commands, and give a flavor for the сапога language 
structure by guiding the reader through a hypothetical editing session. Suppose we are editing the 
following incorrect definition of append: 
[LAMBDA (X) 
Y 


(COND 
((NUL X) 
7 


) 
(Т (CONS (CAR) 
(APPEND (CDR X Y] 


We call the editor via the function editf: 
<EDITF( APPEND) 
EDIT 
ж 


The editor responds by typing EDIT followed by *, which is the editors prompt character, i.e., it 
significs that the editor is ready to accept commands. 


The editor was written by and is the responsibility of W. Teitelman. 
In other words, all lines beginning with * were typed by the user, the rest by the editor. 
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At any given moment, the editor’s attention is centered on some substructure of the expression 
being edited. This substructure is called the current expression, and it is what the user sees when 
he gives the editor the command P, for print. Initially, the current expression is the top level one, 
i.e., the entire expression being edited. Thus: 


*p ; 
(LAMBDA (Х) Y (COND & &)) 
* 


Мое that the editor prints the current expression as though printlevel were set to (2. 20), i.e. 
sublists of sublists are printed as &, tails of long lists printed as -- . The command ? will print the 
current expression as though printlevel were 1000. 


ж ? | 
(LAMBDA (Х) Ү (COND ((NUL Х) 2) (Т (CONS (CAR) (APPEND (CDR Х Y)))))) 


and the command PP will prettyprint the current expression. 


A positive integer is interpreted by the editor as a command to descend into the correspondingly 
numbered element of the current expression. ‘Thus: 


*2 
*р 
(Х) 
ж 


A negative integer has a similar effect, but counting begins from the end of the current expression 
and proceeds backward, i.e., -1 refers to the last element in the current expression, -2 the next to 
the last, etc. For either positive integer or negative integer, if there is no such element, an error 
occurs,’ the editor types the faulty command followed by a ?, and then another *. The current 
expression is never changed when a command causes an error. Thus: | | 


А phrase of the form "the current expression is changed" or "ће current expression becomes’ refers 
to a shift in the editor’s attention, not to a modification of the structure being edited. 


‘Editor errors’ are not of the flavor described in Section 16, ie, they never cause breaks or even go through the 
depends on the context in which the command was being executed. For example, there are conditional commands 
which branch on errors. In most situations, though, an error will cause the editor to type the faulty command 

- followed by а ? and wait for more input. Note that typing control-E while a command is being executed aborts Ше 
command exactly as though it had caused an error. | 
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When the user changes the current expression by descending into it, the old current expression is 
not lost. Instead, the editor actually operates by maintaining a chain of expressions leading to the 
current one. The current expression is simply the last link in the chain. Descending adds the 
indicated subexpression onto the end of the chain, thereby making it be the current expression. 
The command 0 is used to ascend the chain; it removes the last link of the chain, thereby making 
the previous link be the current expression. Thus: 


*p 

X 

#0 P 

(Х) 

“0 -1 Р 

(COND (4 7) (T &)) 


Note the use of several commands оп a single line in the previous output. The editor operates іп 
a line buffered mode, the same as evalgt. Thus no command is actually seen by the editor, ог 
executed, until the line is terminated, either by a carriage return, or a matching right parenthesis. 
The user can thus use control-A and control-Q for line-editing edit commands, the same as he does 
for inputs to evalat. 


In our editing session, we will make the following corrections to append: delete Y "Bom where it 
appears, add Y to the end of the argument list,* change NUL to NULL, change Z to Y, ада Z after 
CAR, and insert a right parenthesis following CDR X. 


First we will delete Y. By now we have forgotten where we are in the function definition, but we 
want to be at the "top" so we use the command 1, which ascends through the entire chain of 
expressions to the top level expression, which then becomes the current expression, i.e., 7 removes 
all links except the first one. 


*^ P 
(LAMBDA (X) Y (COND & &)) 
* 


Note that if we are already at the top, t has no effect, ie. it is a no-op. However, 0 would 
generate an error. In other words, t means "go to the top," while 0 means "ascend one link." 


These two operations could be though of as one opcration, i.e., MOVE Y from its current position to a new position, 
and in fact there is a MOVE command in the editor. However, for the purposes of this introduction, we will confine 
ourselves to the simpler edit commands. 
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The basic structure modification commands in the editor are: 


(n) | п > 1 deletes the corresponding 
element from the current expression. 


(n еу... ер) nm > 1 replaces the nth element in the current expression with — 
еј .. em: | 
(-п e " ет) n,m 21 inserts еј... €m before the nth element in the current 
expression. | 
Thus: 
| ы 
(LAMBDA (X) Y (COND & &)) 
*(3) 
n (X Y)) 


(LAMBDA (X Y) (COND & &)) 


All structure modification done by the editor is destructive, ie, the editor uses rplaca апа rplacd to 
physically change the structure it was given. 


· Note that all three of the above commands perform their operation with respect to the nth element 


from the front of the current expression; the sign ОЁ n is used to specify whether the operation is 
replacement or insertion. Thus, there is no way to specify deletion or replacement of the nth 
element from the end of the current expression, or insertion before the nth element from the end 
without counting out that element's position from the front of the list. Similarly, because we 
cannot specify insertion after a particular element, we cannot attach something at the end of the 
current expression using the above commands. Instead, we use the command N (for nconc). Thus 
we could have performed the above changes instead by: | 


*р 
(LAMBDA (Х) Ү (COND & &)) 


“(1 АМВВА (X Y) (COND а &)) 


Now we are ready to change NUL to NULL. Rather than specify the sequence of descent- 
commands necessary to reach NUL, and then replace it with NULL, e.g, 3 2 1 (1 NULL), we 
will use F, the find command, to find NUL: 
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ж Р ; 
(LAMBDA (X Y) (COND & &)) 
*F NUL | 
*р 
(NUL X) 
*(1 NULL) 
^0 P Е 
((NULL X) 2) 
ж 


Note that F is special in that it corresponds to two inputs. In other words, F says to the editor, 
"treat your next command as an expression to be searched for." The search is carried out in 
printout order in the current expression. If the target expression is not found there, F 
automatically ascends and searches those portions of the higher expressions that would appear after- 
(in a printout) the current expression. If the search is successful, the new current expression will 
be the structure where the expression was found,’ and the chain will be the same as one resulting 
from the appropriate sequence of ascent and descent commands. If the search is not successful, an 
error occurs, and neither the current expression nor the chain is changed: | 


*р 

((NULL X) 2) 
*F COND P 
COND ? 

ер 


*((NULL X) 2) 


Here the search failed to find a cond following the current expression, although of course a cond 
does appear earlier in the structure. This last example illustrates another facet of the error recovery 
mechanism: to avoid further confusion when an error occurs, all commands on the line beyond the 
one which caused the error (and all commands that may have been typed ahead while the editor 
was computing) are forgotten.’ 


We could also have used the R command (for replace) to change NUL to NULL. A command of 
the form (R еј еҙ) will replace all occurrences of еј in the current expression by е». There must 
be at least one such occurrence or the R command will generate an error. Let us use the R 
command to change all Z’s (even though there is only one) in append to Y: | 


5 If the search is for an atom, e.g., F NUL, the current expression will be the structure containing the atom. 

6 F is never а no-op, 1.е., if successful, the current expression after the search will never be the same as the current 
expression before the search. Thus F expr repeated without intervening commands that change the cdit chain can be 
used to find successive instances of expr. 

7 


ie. the input buffer is cleared (and saved) (вес clearbuf, Section 14). It сап be restored, and Ше type-ahead 
recovered via the command $BUFS (esc BUFS), described in Section 22. 
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“ (R ZY) 
"F 


7 7 
«рр 
[LAMBDA (X Y) 
(COND 
((NULL X) 
Y 


(T (CONS (CAR) 
(APPEND (CDR X Y] 


# 


Тһе next task is to change (CAR) to (CAR X). We could do this by (R (CAR) (CAR X)), ог 
бу: 


*F CAR 
*(N X) 
d: 


(CAR X) 
ж 


2 The expression we now want to change is the next expression after the current expression, i.e., we 
are currently looking at (CAR X) in (CONS (CAR X) (APPEND (CDR X Y))). We could get 
to the append expression by typing 0 and then 3 or -1, or we can use the command NX, which 
does both operations: : 


*р 

(САВ Х) 

*NX P 

(APPEND (CDR X Y)) 
* 


Finally, to change (APPEND (CDR X Y)) to (APPEND (CDR X) Y), we could perform (2 
(CDR Х) Y), or (2 (CDR X)) and (МУ), ог 2 and (3), deleting the Y, and then 0 (МУ). 
However, if Y were a complex expression, we would not want to have to retype it. Instead, we 
could use a command which effectively inserts and/or removes left and right parentheses. There 
are six of these commands: BI,BO,LI,LO,RI, and RO, for both in, both out, left in, left out, 
right in, and right out. Of course, we will always have the same number of left parentheses as 
right parentheses, because the parentheses are just a notational guide to structure that is provided 
by our print program. Thus, left in, left out, right in, and right out actually do not insert ог. 
remove just one parenthesis, but this is very suggestive of what actually happens. 


In this case, we would like a right parenthesis to appear following X in (CDR X Y). Therefore, 
we use the command (RI 2 2), which means insert a right parentheses after the second element 
in the second clement (of the current expression): 


Herein lies one of the principal advantages of a LISP oriented editor over a text editor: unbalanced parentheses 
errors are not possible. 
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жр 

(APPEND (CDR Х Y)) 
*(RI 2 2) 

*р 


(APPEND (CDR X) Y) 


We have now finished our editing, and can exit from the editor, to test append, or we could test it 
while still inside of the editor, by using the E command: 


mE шг В) (С. р E)). 
(ABCDE) . 


The E command causes the next input to be given to evalqt. If there is another input following it, 
as in the above example, the first will be E (apply) to the second. Ошен the input 15 
evaluated (eval). 


We prettyprint append, and leave the editor. 


“Pp. 
[LAMBDA (X Y) 
(COND `` 
( (NULL X) 
Y 


Jo 
(T (CONS (CAR X) 
(APPEND (CDR X) У] 
“ОҚ | | 
APPEND - 


€ 


9.2 COMMANDS FOR THE NEW USER 


As mentioned earlier, the Interlisp manual is intended primarily as a reference manual, and the 
remainder of this chapter is organized and presented accordingly. While the commands introduced 
in the previous scenario constitute a complete set, 1.е., the user could perform any and all editing 
Operations using just those commands, there are many situations in which knowing the right 
command(s) can save the user considerable effort. We include here as part of the introduction a 
list of those commands which arc not only frequently applicable but also easy to use. They are not 
presented in any particular order, and are all discussed in detail in the reference portion of the 
chapter. 


UNDO undoes the last modification to the structure being edited, e.g., if 
| the user deletes the wrong clement, UNDO will restore it. The 
availability of UNDO should give the user confidence to experiment 
with any and all cditing commands, no matter how complex, 

because he can always reverse the cffect of the command. 


BK like NX, except makes the expression immediately before the 
current expression become current. 
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BF | backwards find. Like Е, except searches backwards, 1.е., in inverse 
print order. 


\ ~ Restores the current expression to the expression before the last 

| "^ "Ыр jump", eg., a find command, an 7, or another V For 
example, if the user types F COND, and then F CAR, \ would 
take him back to the COND. Another \ would take him back to the 
CAR. | 


\P | | like \ except it restores the edit chain to its state as of the last 
| . print, either by P, 7, or PP. If the edit chain has not been 
changed since the last print, АР restores it to its state as of the 

printing before that one, i.e., two chains are always saved. 


Thus if the user types P followed by 3 2 1 P, XP will take him back to the first P, ie, would 
be equivalent to 0 0 0. Another АР would then take him back to the second P. Thus the user can 
use АР to flip back and forth between two current expressions. 


%,- Тһе search expression given to Ше Р or BF command need not be 
| а literal S-expression. Instead, it can be a pattern. The symbol & 
can be used anywhere within this pattern to match with any single 
element of a list, and -- сап ђе used to match with any segment of a 
list. Thus, in the incorrect definition of append used earlier, 
F (NUL &) could have been used to find (NUL X), and 
F (CDR --) or F (CDR & &), but not F ен &), to find 
(CDR X Y). 


Note that & and -- can be nested arbitrarily deeply in the pattern. For example, if there are many 
places where the variable X is set, F SETQ may not find the desired expression, nor may 
F (SETQ X &). It may be necessary to use F (SETQ X (LIST --)). However, the usual 
technique in such a case is to pick out a unique atom which occurs prior to the desired expression, 
and perform two F commands. This “homing іп" process seems to be more convenient than ultra- 
precise specification of the pattern. 


$ (< esc >) $ is equivalent to -- at the character level, e.g., VERS will match 
| with VERYLONGATOM, as will ФАТОМ, %10М6%, (but not 
$LONG) and $V$NSM$. $ can be nested inside of a pattern, e.g., 

F (SETQ VER$ (CONS --)). 


ТЕ the search is successful, the editor will print = followed by the 
atom which matched with the $-atom, е.р., 
*F (SETQ VERS 8) 
=VERYLONGATOM 
* 


Frequently the uscr will want to replace the entire current рео ог inscrt something before it. 
In order to do this using a command of the form (n c4 .. ) ог Сп су... Cn), the user must be 
above the current expression. In other words, he would jue (0 ОЛИ а 0 followed бу a 
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command with the appropriate number. However, if he has reached the current expression via an 
F command, he may not know what that number is. In this case, the user would like a command 
‚ whose effect would be to modify the edit chain so that the current expression became the first 
element in a new, higher current expression. Then he could perform the desired operation via (1 
ет ... ет) or C1 еј... е). UP is provided for this purpose. 


UP 

(В еу... eq) 
(А ет... ет) 
C eroe) 
DELETE 


after UP operates, the old current expression is the first element of 
the new current expression. Note that if the current expression 
happens to be the first element in tbe next higher expression, then 
UP is exactly the same as 0. Otherwise, UP modifies the edit chain 
so that the new current expression is a tail? of the next higher 
expression: | 


*F APPEND P 
(APPEND (CDR X) Y) 
*UP P 

... (APPEND а Y)) 
*Q P | 


(CONS (CAR X) (APPEND & Y)) 


The .. is used by the editor to indicate that the current expression 
is a гай of the next higher expression as opposed to being an 
element (i.e., a member) of the next higher expression. Note: if the 
current expression is already a tail, UP has no effect. 


inserts еј .. eq, before the current expression, i.e., does an UP and 
then a -1. 


inserts e1 .. €m after the current expression, i.e., does an UP and- | 
then either а (-2 еу... €m) or an (N ej .. €m) if the current 
expression is the last опе 11 the next higher expression. 


replaces current expression by еј ... ед, (е. does an UP and thena _ 
(1 е1 + ет). 


deletes current expression; equivalent to (:). 


Earlier, we introduced the RI command in the append example. The rest of the commands in this 
family: ВТ, BO, LI, LO, and RO, perform similar functions and are useful in certain situations. · 
In addition, the commands MBD and XTR can be used to combine the effects of several commands 
of the BI-BO family. MBD is used to embed the current expression in a larger expression. For 
example, if the current expression is (PRINT bigexpression), and the user wants to replace it by | 


Throughout this chapter "tail" means “proper tail” (see Section 5). 
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(COND (FLG (PRINT bigexpression))), he could accomplish this by (LI 1), (-1 FLG), 
(LI 1), and (-1 COND), or by a single MBD command, page 9.30. 


XTR is used to extract an expression from the current expression. For example, extracting the 
PRINT expression from the above COND could be accomplished by (1), (LO 1), (1) and (LO 1) 
ог by a single XTR command. Тһе new user is encouraged to include XTR and MBD in his 
repertoire as soon as he is familiar with the more basic commands. 


This ends the introductory material. 


9.3 ATTENTION CHANGING COMMANDS 


Commands to the editor fall into three classes: commands that change the current expression (1.е., 
change the edit chain) thereby "shifting the editor's attention," commands that modify the structure 
being edited, and miscellaneous commands, e.g., exiting from the editor, printing, evaluating 
expressions, etc. 


Within the context of commands that shift the editor's attention, we can distinguish among (1) 
those commands whose operation depends only on the structure of the edit chain, e.g., 0, UP, NX; 
(2) those which depend on the contents of the structure, i.e., commands that search; and (3) those 


| commands which simply restore the edit chain to some previous state, e.g., 1, АР. (1) and (2) can 


also be thought of as local, small steps versus open ended, big jumps. Commands of type (1) аге _ 


discussed on page 9.10-14, type (2) on page 9.14-22, and type (3) on page 9.22-23. 


9.3.1 LOCAL ATTENTION-CHANGING COMMANDS 


UP | (1) If a P command would cause the editor to type ... before typing | 
| | the current expression, іс.., the current expression is а tail of the 
next higher expression, UP has no effect; otherwise 
(2) UP modifies the edit chain so that the old-current expression 
(1.е., the one at the time UP was called) is the first element in the - 
new current expression. | 


9 If the current expression is the first element in the next higher expression UP simply does a 0. Otherwise UP adds the 
corresponding tail to the edit chain. | 
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Examples: The current expression in each case is (COND ((NULL X) (RETURN Y))). 


1. “ІР 
COND 
“UP P 
(COND (& &)) 


2, *-1P | 
((NULL X) (RETURN Ү)) 
*UP P 
... ((NULL X) (RETURN Y)) 
*UP P 
... ((NULL X) (RETURN Y))) 


3. *F NULL P 


(NULL X) 

*UP P | 
((NULL X) (RETURN Y)) 
“UP P 


((NULL X) (RETURN Y))) 


The execution of UP is straightforward, except in those cases where tbe current expression appears 
morc than once in the next higher expression. For example, if the current expression is (A NIL 
B NIL C NIL) and the user performs 4 followed by UP, the current expression should then 
be ... NIL C NIL). UP can determine which tail is the correct one because the commands that 
descend save the last tail on an internal editor variable, lastail. Thus after the 4 command is 
executed, lastail is (NIL C NIL). When UP is called, it first determines if the current expression 
is a tail of the next higher expression. If it is, UP is finished. Otherwise, UP computes 
memb[current- expression;next-higher-expression] to obtain a tail beginning with the current. 
expression. H [f there are no other instances of the current expression in the next higher expression, 
this tail is the correct one. Otherwise UP uses lastail to select the correct tail.!? 


n (n > 1) adds the nth element of the current expression to the front of the 
edit chain, thereby making it be the new current expression. Sets 
lastail for use by UP. Generates an error if the current expression 
is not a list that contains at least n elements. 


-n (а > 1) adds the nth element from the end of the current expression to the 
front of the edit chain, thereby making it be the new current 
expression. Sets lastail for use by UP. Generates an error if the 
current expression is not a list that contains at least n elements. 


11 The current expression should always be either a tail or an element of the next higher expression. If it is neither, for 


example the user has directly (and incorrectly) manipulated the edit chain, UP generates an error. 
12 Occasionally the uscr can get the edit chain into a state where lastail cannot resolve the ambiguity, for example if 
there were two non-atomic structures in the same expression that were eq, and the user descended more than one 
level into one of them and then tricd to come back out using UP. In this case, UP prints LOCATION UNCERTAIN 
and gencrates an crror. Of course, we could have solved this problem completely in our implementation by saving at 
each descent both elements and tails. However, this would be a costly solution to a situation that arises infrequently, 
and when it docs, has no detrimental effects. The lastail solution is cheap and resolves 99% of the ambiguities. 
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0 S | Sets edit chain to cdr of edit chain, thereby making the next higher 
| | expression be the new current expression. Generates an error if 
there is no higher expression, i.e., cdr of edit chain is NIL. 


Note that 0 usually corresponds to going back to the next higher left parenthesis, but not always. - 
Бог example, if the current expression is (А B C D E Е B), and the user performs: | 


*3 UP P 
... CDE F G) 
#3 UP P 

ЕЕС) 
#0 P 

C DE F 6) 


If the intention is to go back to the next higher left parenthesis, regardless of any intervening tails, 
the command !0 can be used. | 


0 | | does repeated 05 until it reaches а point where the current 
expression is not a tail of the next higher expression, i.e., aways 
goes back to the next higher left parenthesis. 


1 "4 sets edit chain to last of edit chain, thereby making the top level 
expression be the current түне Меуег generates an error. 


NX effectively dos: ап ИР followed by a 2, M thereby ЕВЕ ће 
current expression be the next expression. Generates an error if 
the current expression is the last one in a list. (However, | NX 
described below will handle this case.) 


BK | makes the current expression be the previous expression in the next 
| higher expression. Generates an error if the current expression is 
the first expression in a list. 


For example, if the current expression is (COND ((NULL X) (RETURN Y))): 


ЖЕ RETURN P 
(RETURN Y) 
*BK P 

(NULL X) 


(NX п)п > 1 equivalent to n NX commands, except if an error occurs, the edit 
| chain is not changed. 


13 10 is pronounced bang-zero. 


14 Both NX and BK operate by performing а !0 followed by an appropriate number, i.e, there won't be an extra tail 


above the new current expression, as there would be if NX operated by performing an UP followed by a 2, 
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(ВК n)n> 1 equivalent to n BK comand except if an error occurs, the edit 
chain is not changed. 
Note: (NX -n) is equivalent to (BK-n), and vice versa. 


INX makes current expression be the next expression at a higher level, 
1е., goes through any number of right кш to get to the 
next expression. 


For example: 
«рр 
(PROG ((L L) 
(UF L)) 
LP (COND 
((NULL (SETQ L (CDR L))) 
(ERROR! )) 
( [NULL E нин (CAR L) 
R L] 
(GO Бри 
(ЕОТТСОМ (QUOTE NX)) 
(SETQ UNFIND UF) 
(RETURN L)) | 
*F CDR P 
(CDR L) 
*NX 
NX 7? 
*INX P. 
(ERRORI) 
*INX P 
((NULL &) (GO LP)) 
*INX P 


(EDITCOM (QUOTE NX)) 
ж 


|МХ operates by doing 05 until it reaches a stage where the current expression is not the last 
expression in the next higher expression, and then does a NX. Thus !NX always goes through at 
least опе unmatched right parenthesis, and the new current expression is always on a different 
level, i.e., INX and NX always produce different results. For example using the previous current 
expression: 


*F CAR P 
(CAR L) 
*INX P 
(GO LP) 
*\P Po 
(CAR L) 
*NX P 
(CADR L) 
» 
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(NTH n) n Е 0 | equivalent to n followed by UP, i.e., causes the list starting with the 
| nth element of the current expression (or nth from the end if 
n < 0) to become the current expression.» Causes an error if 

current expression does not have at least n elements. | 


A generalized form of NTH using location specifications is described on page 9.21. 


Cline-feed > СИГ moves to the "next" expression and prints it, i.e. performs a NX if 
T RM | possible, otherwise performs a !NX. (The latter case is indcated by 
first printing" >" Э 


< control-x > 16 | moves to "previous" thing and then prints it, і.е. performs a BK if 
possible, otherwise a !0 followed by a BK. 


< сопітої-2 >17 — moves to last expression and prints it, ie. does -1 followed by P. 


Both <line-feed>, < control-x >, and <control-z> are immediate read macros; as soon as they 


are read, they abort the current printout. They thus provide a convenient way of moving around | 


in the editor.!? 


9.3.2 COMMANDS THAT SEARCH | 


АП of the editor commands that search use the same pattern matching routine. 19 We will therefore 
begin our discussion of searching by describing the pattern match mechanism. A pattern pat 
matches with x if: ZEE | 


]. pat is eq to x. 

2. pat is &. 

3. pat is a number and eqp to x. 

4, pat is a string and strequal[pat;x] is true. 


5. If car[pat] is the atom “АМҮ”, cdr[pat] is a list of patterns and pat matches x if 
and only if one of the patterns on cdr[pat] matches x. 


15 (NTH 1) is a no-op, as is (NTH -n) where n is the length of the current expression, 
16 <control-A > іп Interlisp оп TOPS-20. 
П <control-L > in Interlisp on TOPS-20. 


18 [n order to facilitate using different control characters for those macros, the function settermchars is provided. It is 
described in Section 14. 


19 


This routine is available to the user directly, and is described on page 9.63. . 
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ба. If pat is a literal atom or string containing one or more < esc > s, each $ can 
match an indefinite number (including 0) of contiguous characters in a literal. 
atom ог string, eg. VERS matches both _VERYLONGATOM and 
"VERYLONGSTRING" as до $LONG$ (but not $LONG), and $V$L$T$. 


6b. If pat is a literal atom or string ending in two <esc>s, pat matches with the 
first atom or string that is "close" to pat, in the sense used by the spelling 
corrector (Section 17). E.g. CONSS$$ matches with. CONS, CNONCS$S$ with 
NCONC ог NCONC1. 
The pattern matching routine always types a message of the form =x to inform 
the user of the object matched by а pattern of type ба ог 66,4 
e.g. =VERYLONGATOM. 


7. If car[pat] is the atom --, pat matches x if 

a. cdr[pat]| = NIL, ie, pat-(—-) eg. | 
(A --) matches (A) (A B C) and (А. B) 
In other words, -- can match any tail of a list. 

b. cdr[pat] matches with some tail of x, 
eg. (A -- (&)) will match with (A B C (D)), |. 
but not (A B C D), or (A B C (D) E). However, 
note that (A -- (&) --) will match with 
(A B C (D) E). 
In other words, -- can match any interior segment of a list. 


8. If car[pat] is the atom ==, pat matches x if and only if cdr[pat] is eq to X. 22 


9. If cadr[pat] is the atom .. pat matches x if car[pat] matches сацх] апа саара | 
is contained in x, as described on page 921. | 


++ 


10. Otherwise if x is a list, pat matches x if car[pat] 
matches car[x], and cdr[pat] matches cdr{x]. 


When the editor is searching, the pattern matching routine is called to match with elements in the 
structure, unless the pattern begins with .., in which case cdr of the pattern is matched against 
proper tails in the structure. Thus if the current expression is (A B C (B C)), X 


*F (B --) 

*P (B C) 

"ОР (... B --) 
ер 


„ВС (B С)) 


Matching is also attempted with atomic tails (except Юг NIL). Thus 


20 except that the atom $ ( < esc >) matches only with itself. 
21 И. = 
unless сдиаше р=7, 
22 Pattern 8 15 for use by programs that call the editor as a subroutine, since апу non-atomic expression in а command 


{урса in by the uscr obviously cannot be са to alrcady existing structure. 
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*p 
(А (В. C)) 

*F С 

ер 

"X p 


Although the current expression is the atom C after the final command, it is printed as ... . C) to 
alert the user to the fact that C is a (ай, not an element. Note that the pattern C will match with 
either instance of C in (A C (B . C)), whereas (... . C) will match only the second C. 
The pattern NIL will only match with NIL as an element, i.e., it will not match in (A B), even 
though cddr of (A B) is NIL. However, (... . NIL) (or equivalently (...)) may be used to 
specify a NIL Jail, ер, (..NIL) will match with cdr of the third subexpression of 
((A . B) (C . D) (E)). | 


. SEARCH ALGORITHM 


Searching begins with the current expression and proceeds in print order. Searching usually means 
find the next instance of this pattern, and consequently a match is not attempted that would leave 
the edit chain unchanged. At each step, the pattern is matched against the next element in the 
expression currently being searched, unless the pattern begins with ... in which case it is matched 
against the next tail of the expression. 


If the match is not successful, the search operation is recursive first in the car direction, and then 
іп the cdr direction, i.e., if the element under examination is а list, the search descends into that 
list before attempting to match with other elements (or tails) at the same level.24 


However, at no point is the total recursive depth of the search (sum of number of cars and cdrs 
descended into) allowed to exceed the value of the variable maxlevel. At that point, the search of 
that element or tail is abandoned, exactly as though the element or tail had been completely 
seatched without finding a match, and the search continues with the element or tail for which the 
recursive depth is below maxlevel. This feature is designed to enable the user to search circular list 
structures (by setting maxlevel small), as well as protecting him from accidentally encountering a 
circular list structure in the course of normal editing. maxlevel is initially set to 300.25 


If a successful match is not found in the current expression, the search automatically ascends to the 
next higher expression," and continues searching there on the next expression after the expression 
it just finished searching. If there is none, it ascends again, etc. This process continues until the 
entire edit chain has been searched, at which point the search fails, and an error is generated. If 
the search fails (or, what is equivalent, is aborted by control-E), the edit chain is not changed (nor 
are any conses performed). 


23 However, there is a version of the find command which can succeed and leave the current expression unchanged 
(see page 9.17). | 
24 There is also a version of the find command (see page 9.18) which only attempts matches at the top level of the 
current expression, i.e., does not descend into elements, or ascend to higher expressions, 
5. maxlevel сап also be set to NIL, which is equivalent to infinity. 
26 


See footnote 21. 
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If the search is successful, 1,е., an expression 15 found that the pattern matches, the edit chain 15 set 
to the value it would have had had the user reached that expression via a sequence of integer 
| commands. 


If the expression that matched was a list, it will be the final link in the edit chain, i.e., the new 
current expression. If the expression that matched is not a list, e.g., is an atom, the current 
expression will be the tail beginning with that atom,’ i.e., that atom will be the first element in the 
new current expression. In other words, the search effectively does an UP „28 


SEARCH COMMANDS 


All of the commands below set lastail for use by UP, set unfind for use by \ (page 9.23), and do 
not change the edit chain or perform any conses if they are unsuccessful or aborted. 


F pattern ic. two commands: the F informs the editor that the next 
command is to bc interpreted as a pattern. This is the most 
common and useful form of the find command. If successful, the 
edit chain always changes, ie. F pattern means find the next 
instance of pattern. 


If membj[pattern; current-expression] is true, F does not proceed 
with a full recursive search. If the value of the memb is NIL, F 
invokes the search algorithm described earlier. 


Thus if the current expression is (PROG NIL LP (COND (-- (GO LP1)))  ... ІРІ. 

.), F LP1 will find the prog label, not the ІРІ inside of the GO expression, even though the 
latter appears first (in print order) in the current expression. Note that 1 (making the atom PROG 
be the current expression), followed by Е LP1 would find the first ІРІ. 


(F pattern N) same as F pattern, i.e., finds the next instance of pattern, except the 
memb check of F pattern is not performed. 


(F pattern T) Similar to F pattern, except may succeed without changing edit 
chain, and does not perform the memb check, 


Thus if the current expression is (COND ..), F COND will look for the next COND, but 
(F COND T) will "stay here”. 


(F pattern п)п > 1 Finds the nth place that pattern matches. Equivalent to (F pattern 
T) followed by (F pattern М) repeated п-1 times. Each time pattern 
successfully matches, n is decremented by 1, and the search 
continues, until n reaches 0. Note that the pattern docs not have to 


27 Unless the atom is a tail, c.g., B in (А . B). In this case, the current expression will be B, but will print as ... . В). 


28 Unless upfindflg = NIL (initially set to T). For discussion, see page 9.28-29. 
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match with n identical expressions; it just has to match n times. 
Thus if the current expression is (Ғ001 Ғ002 ЕООЗ), 
(Е 2008 3) will find Ғ003. 

If the pattern does not match successfully n times, an error is 
generated and the edit chain is unchanged (even if the pattern 
matched п-1 times). 


(F pattern) or only matches with elements at the 
(F pattern NIL) . top level of the current expression, i.e, the search will not descend 
| into the current expression, nor will it go outside of the current 
expression. May succeed without changing edit chain. | 


For example, if the current expression is 
(PROG NIL (SETQ X (COND & &)) (COND &) ...), F COND will find the COND inside 
the SETQ, whereas (Е (COND --)) will find the top level COND, i.e., the second one. 


(FS pattern, .. pattern,) | equivalent to F pattern; followed by Р pattern» ... followed by F 
pattern,, so that if F pattern,, fails, edit chain is left at place 
patterng,.| matched. 


(Ғ- expression x) equivalent to (F (— — . expression) x), i.e., searches for а structure 
eq to expression, see раве 9.15. 


(ОКЕ pattern, - pattern) . equivalent to (F ( *ANY* pattern, . ‚ pattern, ) N), ie. searches for 


an expression that is matched by either RT pattern», ... ... Of 
pattern,. See page 9.14. 


BF pattern backwards find. Searches in reverse print order, beginning with 
| expression immediately before the current expression (unless Ше. 
current expression is the top level expression, in which case BF 

searches the entire expression, in reverse order). 


BF uses the same pattern match routine as F, and maxlevel and 
upfindflg have the same effect, but the searching begins at the end 
of each list, and descends into each element before attempting to | 
match that element. If unsuccessful, the search continues with the 
next previous clement, etc., until the front of the list is reached, at 
which point BF ascends and backs up, etc. 


For example, if the current expression is 

(PROG NIL (SETQ X (SETQ Y (LIST Z))) (COND ((SETQ W --) --)) --), F LIST 
followed by BF SETQ will leave the current expression as (SETQ Y (LIST Z)), as will F COND 
followed by BF SETQ. 


(BF pattern T) search always includes current expression, i.e, starts at the end of 
| | current expression and works backward, then ascends and backs up, 
ctc. | 
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Thus in the previous example, where F COND followed by ВЕ SETQ found _ 


(SETQ Y (LIST Z)), F COND followed by (BF SETQ T) would find the (SETQ W --) 
expression. 


(BF pattern) same as BF pattern. 
(BF pattern NIL) 


(GO label) makes the current expression be the first thing after the prog label 
label, i.e. goes where an executed go would go. 

LOCATION SPECIFICATION 

Many of the more sophisticated commands described later in this chapter use a more general 


method of specifying position called a location specification. A location specification is a list of edit 
commands that are executed in the normal fashion with two exceptions. First, all commands not 


recognized by the editor are interpreted as though they had been preceded by F.?? For example, - 


the location specification (COND 2 3) specifies the 3rd element in the first clause of the next 
COND. 


Secondly, if an error occurs while evaluating one of the commands in the location specification, and 
the edit chain had been changed, 1.е., was not the same as it was at the beginning of that execution 
of the location specification, the location operation will continue. In other words, the location 
Operation keeps going unless it reaches a state where it detects that it is “looping”, at which point 
it gives up. Thus, if (COND 2 3) is being located, and the first clause of the next COND 
contained only two elements, the execution of the command 3 would cause an error. The search 
would then continue by looking for the next COND. However, if a point were reached where there 
were no further CONDs, then the first command, COND, would cause the error; the edit chain 
would not have been changed, and so the entire location operation would fail, and cause an error. 


The IF command in conjunction with the ## function provide а way of using arbitrary 
predicates applied to elements in the current expression. IF and # # will be described in detail 
later in the chapter, along with examples illustrating their use in location specifications. 


Throughout this chapter, the meta-symbol @ is used to denote a location specification. Thus @ is 


a list of commands interpreted as described above. (0) can also be atomic, in which case it is 
interpreted as list[(2]. 


(с. @) provides a way of explicitly invoking the location operation, e.g., 
(LC COND 2 3) will perform the the search described above. 


(LCL . @) same as LC except the search is confined to the current expression, 
ie. the edit chain is rebound during the search so that it looks as 
though the editor were called on just the current expression. For 


29 Normally such commands would cause errors. 


30 Note that the user could always write F COND followed by 2 and 3 for (COND 2 3) if he were not sure whether ог 


not COND was the name of an atomic command, 
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example, to find a COND containing a RETURN, one might use the 
location specification (COND (LCL RETURN) \) where the \ 
would reverse the effects of the LCL command, and make the final 
current expression be the COND. 


Same as (LC . @) followed by another (LC . @) except that if the 
first succeeds and second fails, no change is made to the edit chain. 


Similar to 2ND. 


ascends the edit chain looking for a link which matches pattern. In 
other words, it keeps doing 0’s until it gets to a specified point. If 
pattern is atomic, it is | with the first element of each link, 
otherwise with the entire link? 


[PROG NIL 


*F CADR 


"(е COND) 
*p | 


(COND 


[(NULL (ФЕТО L (CDR L))) 
(COND 
(FLG (RETURN L] 
([NULL (CDR (FMEMB (САВ L) 
(CADR L]] 


(COND (& &) (& &)) 


Note that this command differs from BF in that it does not search inside of each link, it simply 
ascends. Thus in the above example, F CADR followed by BF COND would find 
(COND (FLG (RETURN L))), not the higher COND. 


(BELOW com x) 


If no match is found, an error is generated, and the edit chain is 
unchanged. 


ascends the edit chain looking for a link specified by com, and 
stops x? links below that,? ie. BELOW keeps doing 05 until it gets 
to 2 specified point, and then backs off x 0%. 


31 If pattern is of the form (ТЕ expression), expression is evaluated at each link, and if its value is NIL, ог the 
evaluation causes an error, the ascent continues. 


32 x is evaluated, e.g., (BELOW com (IPLUS X Y)). 


33 


Only links that are elements are counted, not tails, 
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(BELOW com) same as (BELOW com 1). 


For example, (BELOW COND) will cause the cond clause containing the current expression to 
become the new current expression. Thus if the current expression is as shown above, F CADR 
followed by (BELOW COND) will make the new expression | Бе 
([NULL (CDR (FMEMB (CAR L) (CADR L] (GO LP)), and is therefore equivalent to 
000 0. 


The BELOW command is useful for locating a substructure by specifying something it contains. For 
example, suppose the user is editing a list of lists, and wants to find a sublist that contains а FOO 
(at any depth). He simply executes F FOO (BELOW \). 


(NEX x) same as (BELOW x) followed by NX. 

For example, if the user is deep inside of a SELECTQ clause, he can advance to the next clause 
with (NEX SELECTQ). 

NEX same as (NEX ©). 

The atomic form of МЕХ is useful if the user will be performing repeated executions of (МЕХ x). - 


By simply MARKing (see page 9.22) the chain К to x, һе can изе МЕХ to step through 
the sublists. 


(NTH x) generalized NTH command. Effectively - performs (LCL . x), 
followed by (BELOW \), followed by UP. 


In other words, NTH locates x, using a search restricted to the current expression, and then backs 
up to the current level, where the new current expression is the tail whose first element contains, 
however deeply, the expression that was the terminus of the location operation. For example: 

*p | 

(PROG (% 8) LP (COND 8 8) (EDITCOM &) (SETQ UNFIND UF) (RETURN L)) 

2. UF) 


(SETQ UNFIND UF) (RETURN L)) 


If the search is unsuccessful, NTH generates an error and the edit - 

chain is not changed. | 
Note that (NTH п) is just а special case of (NTH x), and in fact, по special check is made for x a 
number; both commands are executed identically. 


(pattern .. (фу ер. (COND .. RETURN). Finds a cond that contains a return, at 


34 


An infix command, ".." is not a meta-symbol, it is the name of the command. @ is cddr of the command. Note that 


(pattern .. @) can aise be used directly as an edit pattern as described on page 9.15, ер. Е (pattern .. (0). 
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any depth. Equivalent to (but more efficient than) (F pattern N), 
(LCL . СО) followed by (© pattern). 


For example, if the current expression is 

(PROG NIL [COND ((NULL L) (COND (FLG (RETURN L] --), then (COND .. RETURN) 
will make (COND (FLG (RETURN L))) be the current expression. Note that it is the innermost 
COND that is found, because this is the first COND encountered when ascending from the RETURN. 
In other words, (pattern .. @) is not always equivalent to (Е pattern М), followed by (LCL . (2) 
followed by \. | 


Note that @ is a location specification, not just a pattern. Thus (RETURN .. COND 2 3) can. 
be used to find the RETURN which contains a COND whose first clause contains (at least) three 
elements. Note also that since СО permits any edit command, the user can write commands of the 
form (COND .. (RETURN .. COND)), which will locate the first COND that contains a RETURN 
that contains a COND. | | 


9.3.3 COMMANDS THAT SAVE AND RESTORE THE EDIT CHAIN 
Several facilities are available for saving the current edit chain and later retrieving it: MARK, which 


marks the current chain for future reference, <,2 which returns to the last mark without destroying 
it, and се, which returns to the last mark and also erases it. | 


МАЯК adds the current edit chain to the front of the list marklst. 


e makes the new edit chain be (CAR MARKLST). Generates an error 
if marklst is NIL, i.e., по MARKs have been performed, or all have 
been erased. | 


ее С | similar to е but also erases the MARK, ie, performs 
(SETQ MARKLST (CDR MARKLST)). ЈЕ 


Note that if the user has two chains marked, and wishes to return to Ше first chain, he must 
perform «+, which removes the second mark, and then +. However, the second mark is then по 
longer accessible. If the user wants to be able to return to either of two (or more) chains, he can 
use the following generalized MARK: 


(MARK atom) sets atom to the current edit chain, 
(\ atom) makes the current edit chain become the value of atom. 


If the user did not prepare in advance for returning to a particular edit chain, he may still be able 
to return to that chain with a single command by using \ or \P. 


35 


An atomic command; do not confuse © with the list command (е pattern), 
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\ makes the edit chain be the value of unfind. Generates an error if 
unfind=NIL. 


 unfind is set to the current edit chain by each command that makes a "big jump", і.е., a command 
that usually performs more than a single ascent or descent, namely t, €, се, INX, all commands 
that involve a search, e.g., Е, LC, .., BELOW, et al and \ and ХР themselves.36 


For example, if the user types F COND, and then Е CAR, \ would take him back to the COND. 
Another \ would take him back to the CAR, etc. 


\P restores the edit chain to its state as of the last print operation, Le., 
Р, 7, or PP. If the edit chain has not changed since the last 
printing, \P restores it to its state as of the printing before that one, 
i.e., two chains аге aways saved. | 


For example, if the user дурез Р followed by 3 2 1 Р, AP will return to the first P, i.e., would 
be equivalent to 0 0 0.37 Another АР would then take him back to the second P, i.e., the user | 
could use АР to flip back and forth between the two edit. chains. | 


(S var . Q) | Sets var (using setq) to the. current expression after Berfonuing 
(LC . @). Edit chain is not changed. 


Thus (5 РОО) will set foo to the current expression, (5 Е 00 E 2 will set foo to the first 
element in the last element of the current SEDI 


This ends the section on "Attention Changing Commands." 


36 Except that unfind is not reset when the current edit chain is the top level expression, since this could always be | 


returned to via the t command. 
37 Note that if the user had typed P followed by F COND, he could use either \ or АР to return to the P, ie, the 
action of \ and АР are independent. | 
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9.4 COMMANDS THAT MODIFY STRUCTURE 


The basic structure modification commands in the editor are: 


(n) | п > 1 deletes the corresponding clement from the current 
expression. 
(n ет... ед) | пт > 1 replaces the nth element in the current expression with 
| еј ра ет: | 
(сп еі - ет) Шш n,m > l inserts еу... €m before the nth element in the current - 
expression. | 2 | 
(Не ... eq) т > 1 attaches ет... е, at the end of the current expression. 


As mentioned earlier: · 


all structure modifi cation done by the bdi, is destructive се, P editor uses acd and rplacd t to 
physically change the structure it was given. · | у 


However, all structure modification 1S undoable, see UNDO page 9. 54. 


АП of the above commis generate errors ar the current expression is. not a list, o or in the case У of 


the first three commands, if the list contains fewer than п elements. In addition, the command (1), 
i.e., delete the first element, will cause an error if there is only one element, since deleting the first 


element must be done by replacing it with the second elemient, and then deleting the second 


element. Or, to look at it another way, deleting the first element when there is only one element 
would require changing a list (0 an. atom (е. to NIL) which cannot be. done. 38 


If the value of changesarray is a hash array, the editor will mark an structures that are changed by 
doing puthash[structurc; fn;changesarray], where fn is the name of the function. The algorithm 
used for marking is as follows: 

(1) Ifthe expression is inside of another expression already marked as being changed, do nothing. 


(2) Ifthe change is an insertion of or replacement with a list, mark the list as changed. 


(3) If the change is an insertion of or replacement with an atom, or a deletion, mark the parent 
as changed. 


38 © However, the command DELETE wil! Work even if there is only one element in the current expression, since it wil - 


aug to a point where it сап do the delction. 
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changesarray is primarily for use by prettyprint (Section 14). When the value of changechar is not 
NIL, prettyprint, when printing to a file or display terminal, prints changechar in the right margin | 
while printing an expression marked as having been changed. changechar is initially |. 


9.4.1 IMPLEMENTATION OF STRUCTURE MODIFICATION COMMANDS 


Note: Since all commands that insert, replace, delete or attach structure use the same low level 
editor functions, the remarks made here are valid for all structure changing commands. 


For all replacement, insertion, and attaching at the end of a list, unless the command was typed in 
directly to the editor? copies of the corresponding structure are used, because of the possibility 
that the exact same command, (i.e., same list structure) might be used again. Thus if a program 
constructs the command (1 (A B C)) e.g., via (LIST 1 FOO), and gives this command to the 
editor, the (A В C) used for the replacement will not be eq to foo. “0 


The rest of this section is included for applications wherein the editor is used to modify a data 
structure, and pointers into that data structure are stored elsewhere. In these cases, the actual 
mechanics of structure modification must be known in order to predict the effect that various 
commands may have on these outside pointers. For example, if the value of foo is cdr of the 
current expression, what will the commands (2), (3), (2 X Y Z), (-2 X Y 7), etc. do to 
foo? | 


Deletion of the first element in the current expression is performed by replacing it with the second 
element and deleting the second element by patching around it. Deletion of any other element is 
done by patching around it, ie. the previous tail is altered. Thus if foo is eq to the current 
expression which is (A B C D), and fie is cdr of foo, after executing the command. (1), foo will 
be (B C D) (which is equal but not e eq to fie. However, under the same initial conditions, 15, after 
executing Q) fie will be unchanged, ie. fie will still be (B C D) even though На current 
expression and foo are now (A C D).# 


Both replacement and insertion. are accomplished by smashing both car and cdr of the 
corresponding tail. Thus, if foo were eq to the current expression, (A B C D), after 
(1 X Y 7), foo would be (X Y Z B C D). Similarly, if foo were (4 to the current expression, 
(A B C D), then after (-1 X У 2), foo would be (X Y ZA B C D). 


The N command is accomplished by smashing the last cdr of the current expression a la nconc. 
Thus if foo were eq to any tail of the current expression, after executing an N command, id, the 
corresponding expressions would also appear at the end of foo. 


39 Some editor commands take as arguments a list of edit commands, e.g., (LP Е FOO (1 (CAR F00))). In this 


case, the command (1 (CAR Ғ00)) is not considered to have been "typed in" even though the LP command itself 
may have been typed in. Similarly commands originating from macros, or commands given to the editor as 
arguments to editf, editv, et al, e.g., EDITF(FOO Е COND (М --)) are not considered typed in. 


The user can circumvent this by using the I command, which computes the structure to be used. In the above 
example, the form of the command would be (I 1 Ғ00), which would replace the first element with the value of 
foo itself. See page 9.42. 


41 


A general solution of the problem just isn't possible, as it would require being able to make two lists ед to each 

other that were originally different. Thus if fie is cdr of the current expression, and fum is cddr of the current 

expression, performing (2) would have to make fie be ед to fum if all subsequent operations were to тиры both бе 
апа fum correctly. Think about it. 
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. In summary, the only situation in which an edit operation will not change an external pointer 
occurs when the external pointer is to a proper tail of the data structure, i.e, to cdr of some node 

jn the structure, and the operation is deletion. If all external pointers are to elements of the 
structure, ie, to car of some node, or if only insertions, replacements, or attachments are 
performed, the edit operation will always have the same effect on an external pointer as it does on 
the current expression. — — 


9.4.2 THE A, B, AND : COMMANDS 


In the (п), (n еу... €m) and (-n е] е.) commands, the sign of the integer is used to indicate | 
the operation. АЕ а result, there b no q rect мау to express insertion after a particular element, | 
(hence the necessity for a separate N command). Similarly, the user cannot specify deletion or 
replacement of the nth element from the end of a list without first converting n to the 
Шаа positive integer. Accordingly, we have: 


(B e .. €m) | inserts e 2. E current expression. Equivalent to UP 
1 т 


followed by С т е 


For example, to insert FOO before the last element in the current expression, perform - d ang then - 


(B ЕОО). 
(А еј ... eq) inserts e e,, after the current expression. Equivalent. to UP 
| followed iby (- 3 еј ... ет) Or (N еу... €n) whichever is appropriate. 
(: еј ... eg) replaces the dne expression by еј... €m. Equivalent to UP 
followed by (1 еј ... 
DELETE or (:) deletes the current expression. 


DELETE first tries to delete the current expression by performing an UP and then a (1). This 
works in most cases. However, if after performing UP, the new current expression contains only 
one element, the command (1) will not work. Therefore, DELETE starts over and performs a ВК, 
followed by UP, followed by (2) For example, if the current expression is 
(COND ((MEMB X Y)) (T Y)), and the user performs -1, and then DELETE, the BK-UP-(2) 
method is used, and the new current expression will be ... ((MEMB X Y))) 


However, if the next higher expression contains only one element, BK will not work. So in this 
case, DELETE performs UP, followed by (: NIL), i.c., it replaces the higher expression by NIL. 
For example, if the current expression is (COND ((MEMB X Y)) (T Y)) and the user performs 
F MEMB and then DELETE, the new current expression will be ... NIL (T Y)) and the 
Original expression would now be (COND NIL (T Y)). The rationale behind this is that deleting 

(MEMB X Y) from ((MEMB X Y)) changes а list of one element to a list of no clements, i.e., O- 
or NIL. 


ТЕ the current expression is a tail, then B, А, :, and DELETE all work exactly the same as though 
the current expression. were the first clement in that tail. Thus if the current expression were 
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... (PRINT Y) (PRINT 7)), (B (PRINT X)) would insert | (PRINT X) _ before 
(PRINT Y), leaving the current expression... (PRINT X) (PRINT Y) (PRINT 2)). 


The following forms of the A, B, and : commands incorporate a location specification: 


(INSERT еј ... eq, BEFORE . (2^? ^ Similar to (LC .@)* followed by (B еу... eg). | 


*р 
(PROG (& & X) **COMMENT** (SELECTQ ATM & NIL) (OR & &) (PRIN1 & T) 
(PRIN1 & T) (SETQ X & 


*(INSERT LABEL BEFORE PRIN1) 
*р 
(PROG (& & Х) **COMMENT** (SELECTQ ATM 8 NIL) (OR & &) LABEL 


(PRIN & T) ( 2i 


Current edit chain is not changed, but unfind is set to the edit 
chain after the B was performed, i.e.,\ will make the edit chain be 
that chain where the insertion was performed. 


(INSERT еј ... е, AFTER . @) 
Similar to INSERT BEFORE except uses A instead of B. 


(INSERT е]... eq, FOR . @) 
similar to INSERT BEFORE except uses : (ог B. _ 


(REPLACE @ WITH ey ... е)“ 
Here @* is the segment of " command between REPLACE and 
WITH. Same as (INSERT € . m FOR. @). : 


Example: (REPLACE COND -1 WITH (T (RETURN L))) 


(CHANGE 8 TO еу... eq) same as REPLACE WITH. 


42 i.e., @ is cdr[member[BE FORE ;command]] 

43 except that if @ causes an error, the location process does лог continue as described on page 9.19. For example if 
(à — (COND 3) and the next COND does not have a 3rd element, the search stops and the INSERT fails. Note that 
the user can always write (LC COND 3) if he intends the search to continue. 

44 


Sudden termination of output followed by a blank line return indicates printing was aborted by control-E. 


45 BY can be used for WITH. 


46 


See footnote on page 9.27. 
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(DELETE . @) . does a (1С. ЕС followed by DELETE. Current cdit chain is not 
changed, ^? but unfind is set to Ше edit chain after the DE LETE was 
performed. 


Example: (DELETE -1), (DELETE COND 3) 


Note: if @ is NIL (ie, empty), the corresponding operation is performed here (on the current edit 
chain). 


For example, (REPLACE WITH (CAR X)) is equivalent to (: (CAR X)). For added 
readability, HERE is also permitted, e.g, (INSERT (PRINT X) BEFORE HERE) will insert 
(PRINT X). before the current expression (but not change the edit chain). 


Note: (2 does not have to specify a location within the current expression, ie, и is perfectly 
legal to ascend to INSERT, REPLACE, or DELETE 


For example, (INSERT (RETURN) AFTER t PROG -1) will go to the top, find the first PROG, 
and insert a (RETURN) at its end, and not change the current edit chain. | 


The A, B, and : commands, commands, (and consequently INSERT, REPLACE, and CHANGE), 
all make special checks in еј thru eq, for expressions of the form (4 # . coms). In this case, the 
expression used for inserting or replacing is a copy of the current expression after exe ving coms coms, a 
list of edit commands.*? For example, (INSERT (44 Е COND -1 -1) AFTER 3)50 will make а 
copy of the last form in the last clause of the next cond, and insert it after the third element of the 
current expression. 


9.4.3 FORM ORIENTED EDITING AND THE ROLE OF UP 


The UP that is performed before A, B, and : commands’? makes these operations form-oriented. 
For example, if the user types F SETQ, and then DELETE, or simply (DELETE SETQ), he will 
delete the entire SETQ expression, whereas (DELETE X) if X is a variable, deletes just the variable 
X. In both cases, the operation is performed on the corresponding form, and in both cases is 
probably what the user intended. Similarly, if the user types (INSERT (RETURN Y) BEFORE 


47 See footnote on page 9.27. 


48 Unless the current expression is no longer a part of the expression being edited, e.g., if the current expression is ... 
C) and the user performs (DELETE 1), the tail, (C), will have been cut off. Similarly, if the current expression is 
(CDR Y) and the user performs (REPLACE WITH (CAR X)). | 


49 The execution of coms does not change the current edit chain. 


50 Not (INSERT Е COND -1 (ҰЯ -1) AFTER 3), which inserts four elements after the third element, namely Е, 
COND, -1, and а сору of the last element in the current expression. 


51 and therefore in INSERT, CHANGE, REPLACE, and DELETE commands after the location portion of the. 
operation has been performed. | 
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SETQ), he means before the SETQ expression, not before the atom SETQ. 52 A consequent of this 
procedure is that a pattern of the form (SETQ Y --) can be viewed as simply an elaboration and - 
further refinement of the pattern SETQ. Thus (INSERT (RETURN Y) BEFORE SETQ) and 
(INSERT (RETURN Y) BEFORE (ФЕТО У --)) perform the same operation?? and, in fact, this 
is one of the motivations behind making the current expression after F SETQ, and F (ЕО Y 
--) be the same. 


Occasionally, however, a user may have a data structure in which no special significance or 
meaning is attached to the position of an atom in a list, as Interlisp attaches to atoms that appear 
as car of a list, versus those appearing elsewhere in a list. In general, the user may not even know 
whether a particular atom is at the head of a list or not. ‘Thus, when һе writes 
(INSERT expression BEFORE FOO), he means before the atom FOO, whether or not it is car of a 
list. By setting the variable upfindflg to NIL,>* the user can suppress the implicit UP that follows 
searches for atoms, and thus achieve the desired effect. With upfindflg = NIL, following Е FOO, 
for example, the current expression will be the atom #00. In this case, the A, В, апа: 
operations will operate with respect to the atom FOO. If the user intends the operation to refer to 
the list which FOO heads, he simply uses instead the pattern (FOO --). 


9.4.4 EXTRACT AND EMBED 

Extraction involves replacing the current expression with one of its subexpressions (from any 

depth). 

(ХТА . (2) replaces the original current expression with the “expression that 15 
current after performing (LCL . @). | | 


For example, if Ше current expression is (COND ((NULL X) (PRITNI ү))), (XTR PRINT), 
or (XTR 2 2) will replace the cond by the print. | 


If the current expression after (ІСІ. @) is а гай of a higher 
expression, its first element is used. 


For example, if the current expression is (COND ((NULL X) Y) (T Z)), then (XTR Y) will 
replace the cond with Y, even though the current expression after performing (LCL Y) 15... Y). 


If the extracted expression is a list, then after XTR has finished, the 
current expression will be that list. 


Thus, in the first example, the current expression after the XTR would be (PRINT Y). 


52 There is some ambiguity in (INSERT expr AFTER functionname), as the user might mean make expr be the 


function's first argument. Similarly, the user cannot write (REPLACE SETQ WITH SETQQ) meaning change the 
name of the function. The user must in these cases write (INSERT expr AFTER functioname 1), and (REPLACE 
ФЕТО 1 WITH 5ЕТОО). | 


53 assuming the next SETQ is of the form (SETQ Y --). 


54 Initially, and usually, set to Т. 


55 


ӛсе footnote on page 9.27. 
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If the extracted expression is not a list, the new current САРГОН 
will be a tail whose first clement is that non-list. 


Thus, in the second example, the current expression after the XTR would be .. Y followed by 
whatever followed the COND. 


If the current expression initially is a tail, extraction works exactly the same as though the current 
expression were the first element in that tail. Thus if the current expression is 

(COND ((NULL X) (PRINT Y))) (RETURN Z)), then (XTR PRINT) will replace the 
cond by the print, leaving (PRINT Y) as the current expression. 


“Тһе extract command сап also incorporate a location specification: 


(EXTRACT 1 FROM. 95)? Performs (LC . 5)" and then (ХТА. @1). Current edit chain is 


not changed, but ба is set to the cdit. chain after the XTR was 
performed. 


Example: If the current expression is (PRINT (COND ((NULL X) Y) (T Z))) then following 
(EXTRACT Y FROM COND), the current expression will be (PRINT Y). 
(EXTRACT 2 -1 FROM COND), (EXTRACT Y FROM 2), (EXTRACT 2 -1 FROM 2) will all 
produce the same result. | E 


While extracting replaces the current expression by a subexpression, embedding replaces the 


current expression with one containing if as a subexpression. 


(MBD съ... ет) | MBD substitutes? the current expression. for all instances of the 


atom * in еу... €m and replaces the current expression with the 
result of that substitution. 


Examples: If the current expression is (PRINT Y), | 
(MBD (COND ((NULL X) *) ((NULL (CAR Y)) * (GO LP)))) would replace (PRINT ү) 
with (COND ((NULL X) (PRINT Y)) ((NULL (САК Y)) (PRINT Y) (GO LP))). 


If the current expression is (RETURN X), (MBD (PRINT Y) (AND FLG *)) would replace it 
with the two expressions (PRINT Y) and (AND FLG (RETURN X)) ie, if the (RETURN X) 


appeared in the cond clause (T (RETURN X)), after the MBD, the clause would be 


(T (PRINT Y) (AND FLG (RETURN X))). 


If * does not appear in ет... ер, the MBD is interpreted as 
(МВО (еј ... е *)). 

Examples: If the current expression is (PRINT Y), Шеп (MBD SETQ Х) will replace it with 

(SETQ X (PRINT Y)). If the current expression is (PRINT Ү), (MBD RETURN) will replace 


it with (RETURN (PRINT Y)). 


56 а, is Ше segment between EXTRACT and FROM. 


57 See footnote on page 9.27. 


58 as with subst, a fresh copy is used for cach substitution. 
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MBD leaves the edit chain so that the larger expression is the new current expression. 


Jf the current expression initially is a tail, embedding works exactly the same as though the current 
expression were the first element in that tail. Thus if the current expression were ... 
(PRINT Y) (PRINT 2)), (MBD SETQ X) would replace (PRINT Y) with (SETQ X 

(PRINT Y)). | | 


The embed command сап also incorporate a location specification: 
(EMBED @ IN . x)? does (LC . @)® and then (MBD . x). Еди chain is not changed, but 
 unfind is set to the edit chain after the MBD was performed. 


Example: (EMBED PRINT IN SETQ X), (EMBED 3 2 IN RETURN), 
(EMBED COND 3 1 IN (OR * (NULL X))). 


WITH can be used for IN, and SURROUND can be used for EMBED, eB. (SURROUND NUMBERP 
WITH (AND * (MINUSP X))). 


9.4.5 THE MOVE COMMAND 


The MOVE command allows the user to specify (1) the expression to be moved, (2) the place it is to 
be moved to, and (3) the operation to be performed there, e.g., insert it before, insert it after, 
replace, etc. | | 


(MOVE (64 ТО com. @,)* where com is BEFORE, AF TER, or the name of a list СР 
E ES СМ, etc. performs (LC . а p and obtains the current 
expression there (or its first ас if it is a tail), which we will 


call expr; MOVE then goes back to as original edit chain, performs “| 


(LC . 25) followed by (com ехрг),93 then goes back to (2i and 
deletes expr. Edit chain is not changed. Unfind is set to edit tain 
after (com expr) was performed. 


For example, if the current expression is (A B C D), (MOVE 2 TO AFTER 4) will make the 


new current expression be (A C D B). Note that 4 Was executed as of the original edit chain, 
and that the second element had not yet been removed. 


59 @ is the segment between EMBED and ІМ. 


60 See footnote on page 9.27. 

61 @, is the scgment between MOVE and ТО. 
62 sce footnote on page 9.27. 

63 Setting an internal flag so expr is not copied. 
64 


If а, specifies a location inside of the expression to be moved, a message is printed and an crror is generated, e.g., 
(MOVE 2 TO AFTER X), where X is contained inside of the second element. 
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As the following examples taken from actual editing will show, the MOVE command is an extremely 
versatile and poweri feature of the editor. 


*? 

(PROG ((L L)) (EDLOC (CDDR C)) (RETURN (САВ L))) 
“(MOVE 3 TO : CAR) 

к? 

(PROG ((L L)) (RETURN (EDLOC (CDDR C)))) 


«p 

(SELECTQ OBJPR & &) (RETURN &) LP2 (COND 8 8) 
*(MOVE 2 TO N 1) 
*p | | 

(SELECTQ ОВЈРА & 8: 8) 1Р2 (COND & 48)) 


ж 

жр 

(OR (EQ Х LASTAIL) (NOT 8) (AND & 8, &)) 
“(MOVE 4 TO AFTER (BELOW СОМО)) 


*р 
(OR (EQ Х LASTAIL) (NOT &)) 
*\ р 
(& &) (AND & & &) (T & &)) 
225 


((NULL X) **COMMENT** (COND & &)) 
*(-3 (GO NXT] 

*(MOVE 4 TO N (е PROG)) 

хр m 


((NULL X) **COMMENT** (GO NXT)) 

*\ P 

(PROG (&) **COMMENT** (COND & & 8) (COND & 8 &) (COND & &)) 
*(INSERT NXT BEFORE -1): 

«p 

(PROG (&) **COMMENT** (COND & & &) (COND & & 4) NXT (COND 8 &)) 


Note that in the last example, the user could have added the prog label NXT and moved the cond 

. jn one operation by performing (MOVE 4 TO N (e PROG) (М NXT)). Similarly, іп the next 
example, in the course of specifying (9., the location where the expression was to be moved to, the 
user also performs a structure шошо, ча (М (T)), thus creating the structure that will 
reccive the expression being moved. - » 


«p 

((CDR &) **COMMENT** (SETQ CL &) (EDITSMASH CL & &)) 
"МОМЕ 4 TO N 0 (N (T)) -1] 

*р 

((CDR &) **COMMENT** (SETQ CL &)) 

"у р 

“(Т (EDITSMASH CL 8 &)) 

ж 


If (O^ is NIL, or (HERE), the current position specifics where the operation is to take place. In this 
case, unfind is set to where the expression thal was moved was originally located, 1.с., (21. Бог 
example: | 
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*р 

(ТЕМЕХ) 

“(МОМЕ t Е APPLY ТО N HERE) 
ар 

(ТЕМЕХ (APPLY & &)) 

* 8 


жр 

(PROG (% & 8 ATM IND VAL) (OR & &) **СОММЕМТ** (OR 4 8) 
(РВ1М1 & Т) ( 

PRIN1 & Т) (SETQ IND 


"(МОМЕ * TO BEFORE bu: 
«p 
(PROG (8 & & ATM. IND VAL) (OR & 8) (OR 8 8) (PRIN1 8 


*р 

(T (PRIN1 С-ЕХР T)) 

*(MOVE + BF PRIN1 ТО М HERE) 

*р 

(T (РЕТКА С-ЕХР Т) (PRINI & T)) 


Finally, if (21 is NIL, the MOVE command allows the user to specify where the current expression 
is to бе inoved to. In this case, the edit chain is changed, and is the chain where the current 
expression was moved to; unfind is set to MIC it was. 


«р 

(SELECTQ OBJPR (8) (PROGN 8 &)) 

*(MOVE TO BEFORE LOOP) 

«р 

... (SELECTQ ОВЈРА & &) LOOP (FRPLACA DFPRP &) (FRPLACD DFPRP 
&) (SELECTQ 

* 


9.4.6 COMMANDS THAT MOVE PARENTHESES 


Тһе commands presented in this section permit modification of the list structure itself, as opposed 
to modifying components thereof. Their effect can be described as inserting or removing a single 
left or right parenthesis, or pair of left and right parentheses. Of course, there will always be the 
same number of left parentheses as right parentheses in any list structure, since the parentheses are | 
just a notational guide to the structure provided by print. Thus, no command can insert or remove . 
just one parenthesis, but this is suggestive of what actually happens. 


In all six commands, n and m are uscd to specify an element of a list, usually of the current 
expression. Іп practice, п and m are usually positive or negative integers with the obvious 
interpretation. However, all six commands use the gencralized NTH command, page 9.21, to find 
their element(s), so that nth element means the first clement of the tail found by performing (NTH 
n) In other words, if the current expression is (LIST (CAR X) (SETQ Y (CONS W 2))), 
then (BI 2 CONS), (BI X -1), and (BI X Z) all specify the exact same opcration. 


65 


. Sudden termination of output followed by a blank line indicates printing was aborted by control-E. 
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All six commands generate an error if the element is not found, i.e., the NTH fails. АП are 
undoable. | 


(BI n m) both in, inserts a left parentheses before the nth element and after 
| the mth element in the current expression. Generates an error if 
the mth element is not contained in the nth tail, іс. the mth 

element must be "to the right" of the nth element. | 


Example: If the current expression is (A B (C D E) F G), then (BI 2 4) will modify it to 
be (A (B (C D E) Ғ) 6). | 


(BI n) same as (BI n n). 


Example: If the current expression is (A B. (C D E) F G), then (BI -2) will modify it to be 
(A B (C D E) (Ғ) 6). 


_ (BO n) both out  Removes both parentheses from the nth element. 


Generates an error if nth element 3 is not a list. 


Кйшй If the current expression 15 (А В К р Е) Е б), then (BO D) will П modify i it to be 
(ABCDEFG). 


(LI n) | | left in, inserts a left parenthesis before the nth element (and а | 
| matching right parenthesis at the end of the current expression), i.e. 
equivalent to (BI n -1). | 


Example: if the current expression is (A B (C D E) F G), then (LI 2) will modify it to be 
(A (B (C D E) F G)). 


(LO n) с lef out, removes a left parenthesis from the nth element. All 
elements following the nth element are deleted. Generates an error 
if nth element is not a list. 


Example: If the current expression is (A B (C D E) F G), then (LO 3) will modify it to be 
(ABCD Е). 


(RInm) | Ж right іп, inserts а right parenthesis after the mth element of the nth 
| | element. The rest of the nth element is brought up to the level of 
the current expression. 


Example: If the current expression is (A (B C D E) Ға), (RI 2 2) will modify it to be _ 


(А (B C) D E F 6). Another way of thinking about RI is to read it as "move the right. 
parenthesis at the end of the nth element їп to after its mth element." 


(RO n) . . Tight out, removes the right parenthesis from the nth element, 
moving it to the end of the current expression. АП elements 
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following the nth element are moved inside of the nth clement. 
Generates an error if nth element is not a list. | 


‘Example: If the current expression is (A B (C D E) F G), (RO 3) will modify it to ђе (A B 
(CD E F G)). Another way of thinking about RO 15 to read it as "move Ше right parenthesis at 
the end of the nth element out to the end of the current expression." 


9.4.7 TO AND THRU 


EXTRACT, EMBED, DELETE, REPLACE, and MOVE can be made to operate on several 
contiguous elements, 1.е., a segment of a list, by using in their respective location specifications the 
TO or THRU command. 


(Ф) THRU (2) does a (С. (01), followed by an UP, and then а (BI 1 @)), 
thereby grouping the segment into a single element, and finafly 
does a 1, making the final current expression be that element. 


For example, if the current expression is (А (В (C D) (Е) (F GH) I) J K), following 
(C THRU а), the current expression will be ((С D) (E) (F G H)). 


(Ф) TO Q») Same as THRU except last element not included, i.e., after the BI, 
an (RI 1 -2) is performed. 


If both (O1 and (Q^ are numbers, and (Q^ is greater than @), then (Фу counts from the beginning 
of the current expression, the same as (24. In other words, if. the current expression is 
(ABCDEF а), (3 THRU 5) means (C THRU E) not (C THRU G). In this case, the 
corresponding BI command is (BI 1 (25-(2, +1). | 


THRU and ТО аге not very useful commands by themselves; they are intended to be used іп 
conjunction with EXTRACT, EMBED, DELETE, REPLACE, and MOVE. After THRU and TO have 
operated, they set an internal editor flag informing the above commands that the element they are 
Operating on is actually a segment, and that the extra pair of parentheses should be removed when 
the operation is complete. Thus: 0 | | | 
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*р | 
(PROG (% & ATM IND VAL WORD) (PRIN1 & T) (PRIN1 & Т) (SETQ IND &) 
(SETQ VAL &) **СОММЕМТ** (SETQQ 


*(MOVE (3 THRU 4) TO BEFORE 7) 
*р 


 (PROG (& & ATM IND VAL WORD) (SETQ IND 8) (SETQ VAL &) (PRIN1 & T) 


(PRIN1 & T) **COMMENT** 


* 


ер 
(* FAIL RETURN FROM EDITOR. USER SHOULD NOTE THE VALUES OF SOURCEXPR 
AND CURRENTFORM.  CURRENTFORM IS THE LAST FORM IN SOURCEXPR WHICH 


. MILL HAVE BEEN TRANSLATED, AND IT CAUSED THE ERROR. ) 


"(DELETE (USER THRU CURR$)) 
=CURRENTFORM. 
*р 


(* FAIL RETURN FROM EDITOR. CURRENTFORM IS 


ж 


*p 
... LP (SELECTO & & & & NIL) (SETQ Y 8) OUT Г (SETO FLG " (RETURN Y) 
s (MOVE (1 TO OUT) ТО N HERE]. 


OUT (SETQ FLG &) (RETURN Y) LP (SELECTQ & & & & NIL) (SETQ Y в) 


«рр | 
[PROG (ВЕ TEMP1 ТЕМР2) 
(COND | 
((МОТ (МЕМВ ВЕМАВС LISTING)) 
(SETQ TEMP1 (ASSOC REMARG NAMEDREMARKS)) + "COMMENT** 
(SETQ TEMP2 (CADR TEMP1)) 
(СО SKIP)) 
(T **СОММЕМТ** 
(SETQ TEMP1 REMARG))) 
(NCONC1 LISTING REMARG) 
(COND 
((NOT (SETQ TEMP? (SASSOC 


*(EXTRACT (SETQ THRU CADR) FROM COND) 

«p 

(PROG (RF TEMP1 TEMP2) (SETQ TEMP1 &) **COMMENT** (SETQ TEMP2 &) 
(МСОМС1 LISTING REMARG) (COND & & 


% 


9.36 


Commands That Modify Structure | 


TO and THRU can also be used directly with XTR.S6 Thus in the previous example, if the current 
expression had been the COND, e.g., the user had first performed F COND, he could have used 


(XTR (SETQ THRU CADR)) to perform the extraction. 


(@ TO), (2) THRU) both same as (Фа THRU -1), i.e., Кот @, ПОО the end 
| of the list. 
Examples: 
жр 
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(VALUE (RPLACA БЕРЕР &) (RPLACD 8.) (RPLACA VARSWORD &) (RETURN) 
*(MOVE (2 TO) TO М (« PROG)) 


«(М (GO VAR)) 
ер 


(VALUE (СО VAR)) 


*p 

(T **COMMENT** (COND 8) **COMMENT** (EDITSMASH CL & &) (COND &)) 
*(-3 (GO REPLACE)) 

*(MOVE (COND TO) TO N * PROG (N REPLACE)) 

ж P | 


(Т **COMMENT** (СО REPLACE)) 
*“\ P 


(PROG (&) **COMMENT** (COND & & &) (COND & & &) DELETE (COND & &) 
REPLACE (COND &) **COMMENT** (EDITSMASH CL & &) (COND &)) 


Because XTR involves a location specification while A, B, :, and MBD do not. 
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«рр. 
[LAMBDA (CLAUSALA X) 
(PROG (A D) 
(ЗЕТО A CLAUSALA) 
LP (COND | 
((NULL A) 
(RETURN) )) 
(SERCH X A) 
(RUMARK (CDR A)) 
(NOTICECL (CAR A)) 
(SETQ A (CDR A)) | 
(GO LP] 
“(EXTRACT (SERCH THRU LR) FROM PROG) 
-NOTICECL 
*р 
(LAMBDA (CLAUSALA X) (SERCH X А) (RUMARK &) (NOTICECL &)) 
*(EMBED (SERCH TO) IN (MAP CLAUSALA (FUNCTION (LAMBDA (A) *] 
*рр 
[LAMBDA (CLAUSALA Х) 
(MAP CLAUSALA (FUNCTION (LAMBDA (A) 
J (SERCH X А) 
(RUMARK (CDR A)) 
(NOTICECL (CAR A] 


9.4.8 THE R COMMAND 


(R x y) | replaces all instances of x by y in the current expression, e.g., 
(R CAADR CADAR). Generates an error if there is not at least one 
instance. 


The R command operates in conjunction with the search mechanism of the editor. The search 
proceeds as described on page 9.16-17, and x can employ any of the patterns on page 9.14-16. 
Each time x matches an element of the structure, the element is replaced by (a copy of) y; each 
time x matches a tail of the structure, the tail is replaced by (a copy of) y. 


For example, if the current expression is (A (B C) (B . C)), 
(R C D) will change it to (А (B D) (В. D)), | 
(R.(... . С) D) to (A (B C) (В. D)), 


(ВС (D E)) to (A (B (D E)) (B D E)), and 


(R (... . NIL) D) о (А (BC . D) (B.C). D). 


If x is an atom or string containing <esc>s, <esc>s appearing in y stand for the characters 

matched by the corresponding < еѕс> іп x. For example, (В Ғ00% Ди means Юг all atoms 
or strings that begin with FOO, replace the characters "FOO" by "ЕТЕ".®? Applied to the list 
(FOO F002 ХҒ001), (В F00$ ҒІЕ%) would produce (ЕТЕ FIE2 ХЕОО1), and 


67 If x matches a string, it will be replaced by a string. Note that it does not matter whether x or y themselves are 


strings, іс. (R 505 $А$), (В "$0$" $AS), (R 50% "$А$"), and (R "505" "$A$") are equivalent. Note 
also that x will never match with a number, ie, (R $1 $2) will not change 11 to 12. 
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(В ФЕООФ $FIE$) would produce (ЕТЕ FIE2 XFIE1). Similarly, Ae 505 $А$) will change | 
(LIST (CADR X) (CADDR Y)) to (LIST (CAAR X) (CAADR)).° 


The user will be informed of all such «esc? replacements by a message of the form x->y, eg., 
CADR->CAAR. 


Note that the $ feature can be used to delete or add characters, as well as replace them. For 
example, (R $1 $) will delete the terminating 15 from all literal atoms and strings. Similarly, if an 
< еѕс> in x does not have a mate in y, the characters matched by Ше $ are effectively deleted. 
For example, (R $/$ $) will change AND/OR to АМО. 69 y can also be а list containing < esc s, 
e.g., (В $1 (CAR $)) will change F001 to (CAR FOO), FIE1 to (CAR ЕТЕ). | 


If x does not contain < esc >s, $ appearing in y refers to the entire expression matched by x, ев. 
(В LONGATOM '$) changes LONGATOM to 'LONGATOM, (R (SETQ X &) (PRINT $)) 
changes every (ФЕТО X &) to (PRINT (SETQ X &)). 0 | 


Since (R $x$ $y$) is a frequently used operation for replacing characters, the following command is 
provided: | 


(RC x y) equivalent to (R $x$ $y$) 


R and RC change all instances of x to y. The commands R1 ad RC1 are available for changing 
ња опе, (i.e., the first) instance of 3 х to y. 


(R1 x y) | find the first instance of x and replace it by y. 
(RC1 x y) | = (R1 $x$ $y$). 


In addition, while В and RC only operate within the current expression, R1 and RC1 will continue ` 
searching, a la the F command, until they find an instance of x, even if the search carries them 
beyond the current expression. | 


(SW n m) switches the nth and mth elements of the current expression. 


For example, if the current expression is 
(LIST (CONS (CAR X) (CAR Y)) (CONS (CDR X) (CDR Y))), 


68 Note that CADDR was пог changed to CAAAR, i.e, (R 505 $A$) does not mean replace every D with A, but replace 
the first D in every atom or string by A. If the user wanted to replace every D by A, he could perform | 
(LP (R 505 $A$)). 


69 However, there is no similar operation for changing AND/OR to OR, since the first $ in y always corresponds to the 


first $ in x, the second $ in y to the second in x, etc. 
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If x is a pattern containing ап <esc> pattern somewhere within it, the characters matched by the € esc? s are not 
available, and for the purposes of replacement, the effect is the same as though x did not contain апу < esc? s. For 
cxample, if the user types (R (CAR F$) (PRINT $)), the second $ will rcfer to the entire expression matched 
by (CAR F$). | 
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(SW 2 3) will modify it to ђе _ 
(LIST (CONS (CDR X) (CDR Y)) (CONS (CAR X) (CAR Y))). The relative order of n 
and m is not important, i.e., (SW 3 2) and (SW 2 3) are equivalent. | 


SW uses the generalized NTH command to find the nth and mth 
elements, a la Ше BI-BO commands. 


Thus in the previous example, (SW CAR CDR) would produce the same result. 


(SWAP (21 (22) | ike SW except switches the expressions specified by СТ and (22, 


not the corresponding elements of the current expression, ie. (21 
and @2 can be at different levels in current expression, or one ог 
both be outside of current expression. . 


Thus, using the previous example, (SWAP CAR СОК) would тезі in 
(LIST (CONS (CAR X) (CDR Y)) (CONS (CDR X) (CAR Y))). ; | 


9.5 COMMANDS THAT PRINT . 


PP prettyprints the current expression. 
Р | | prints the current expression as though printlevel were ч 2 а 
(Pm) | | prints mth element of current expression as though printlevel were 

set to 2. _ 

(0 | same т Р 

(P m n) | prints mth element of current expression as though printlevel w were | 
set to n. 

(P 0 n) |. A prints current expression as though printlevel were set to n. 

9 same às (P 0 100) 


Both (P m) and (P m n) use the generalized NTH command to obtain the corresponding element, 
so that m docs not have to be a number, е.р., (P COND 3) will work. PP causes all comments to 
be printed as **COMMENT** (see Section 14). P and ? print as **COMMENT** ш. those 
comments that are (top level) elements of the current expression./2 


Lower expressions are not really seen by the editor; the printing command simply sets printlevel and calls print. 
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РР“ prettyprints current expression, including comments. 


РР“ is equivalent to PP except that it first resets **comment**flg to NIL (see Section 14). 


PPV prettyprints current expression as a variable, ie. по special 
treatment for LAMBDA, COND, SETQ, etc., or for CLISP. 


PPT prettyprints current expression, printing CLISP translations, if any. 


I= prints the argument names and corresponding values for current 


expression. Analagous to ?= break command (Section 15). 


For example, if the current expression is (STRPOS "A0???" X N (QUOTE 7) T), ?= prints 


X = "А0???" 
Y= X 

START = N 

SKIP = (QUOTE ?) 

ANCHOR = T 

TAIL = 72 


All printing functions print to the terminal, regardless of the primary output file. All use the | 


readtable T. No printing function ever changes the edit chain. All record the current edit chain 
for use by \P, page 9.23. All can be aborted with cone Е. 


9.6 COMMANDS THAT EVALUATE 


E only when typed in,’ causes the editor to call lispx giving it the 
next input as argument. 


Example: 
*E BREAK(FIE FUM) 
(FIE FUM) 
*E (FOO) 


(FIE BROKEN) 


72 The command MAKE described on page 9.54 is ап imperative form of ?=. It allows the user to specify a change to 
the element of the current expression that corresponds to a particular argument name. | 

73 e.g, (INSERT D BEFORE E) will treat E as а pattern, and search for E. 

74 


lispx is used by cvalgt and break for processing terminal inputs. If nothing else is typed on the same line, lispx 
evaluates its argument. Otherwise, lispx applics it to the next input. In both cases, lispx prints the result. Sce above 
exumple, and Sections 2 and 22, 
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(E x) | 24 evaluates x, ie. performs eval[x], and prints the result on the 


terminal. 
(E x T) | same as (E x) but does not print. 


The. (E x) and (E x T) commands are mainly intended for use by macros and subroutine calls to 
the editor; the user would probably type in a form for evaluation usir using the more convenient 
format of the (atomic) E command. 


(Ic xy ... Xp) mE same as (C ут... yg) where уу —eval[xi]. 


Example: (I 3 (GETD (QUOTE F00))) will replace the 3rd element of the current expression 
with the definition of foo. (I N FOO (CAR FIE)) will attach the value of foo and car of the 
value of fie to the end of the current expression. (I Ғ- FOO T) will search for an expression eq 
to the value of foo. 


If c is not an atom, c is evaluated also. 


Example: (I (COND ((NULL FLG) (QUOTE -1)) (T 1)) FOO), if Яр is NIL, inserts the 
value of foo before the first element of the current expression: otherwise ae the first clement E 


oru the value of foo. 


EVAL does an eval of the current expression. 


Note that EVAL, <line-feed>, and the GO command together effectively allow the user. to 
“single-step” a program through its symbolic definition. 


GETVAL 8 74 replaces the current expression by the result of evaluating it. 


# # [com] ;com3; Ва. “сот is ап NLAMBDA, NOSPREAD function (not а command). Its value is 
| what the current expression would be after executing the edit 
commands com; .. com, starting from the present edit chain. 
Generates an error if any of com] thru com, cause errors. Тһе 

current edit chain is never спапред.76 


15 The I command sets an internal Пар to indicate to the structure modification commands not to copy expression(s) 
when inserting, replacing, or attaching. · 


76 Recall that A, B, :, INSERT, REPLACE, and CHANGE make special checks for # # forms in the expressions 
used for inserting or replacing, and use а copy of ## form instead (see page 928). Thus, ( INSERT 
(## 3 2) AFTER 1) is equivalent to (I INSERT (COPY (## 3 2)) (QUOTE AFTER) 1). 
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Example: (I R (QUOTE X) (## coe .. Z))) replaces ай X’s in the current expression by 
the first cons containing a Z. | | 


“Тһе I command is not very convenient for computing ап entire edit command for execution, since 
it computes the command name and its arguments separately. Also, the I command cannot be | 
used to compute an atomic command. The following two commands provide more general ways of 

computing commands. 


(COMS хү... X9) Each x; is evaluated and its value is executed as a command. 


For example, (COMS (COND (X (LIST 1 X)))) will replace the first element of the current 5 
expression with the value of x if non-NIL, otherwise do nothing. 


(COMSQ com ... сот) executes com ... COM». 


COMSQ is mainly useful in conjunction with the COMS command. For example, suppose the user 
wishes to compute an entire list of commands for evaluation, as opposed to computing each 
command one at a time as does the COMS command. He would then write (COMS (CONS 
(QUOTE COMSQ) х) where x computed Ше list of commands, ер, 
(COMS (CONS (QUOTE COMSQ) (GETP FOO (QUOTE COMMANDS)))). Е 


9.7 COMMANDS THAT TEST 


(IF x) generates an error unless the value of evallx] i is true, ie. if evallx] 
causes an error or eval[x]=NIL, IF will cause an error. | 


For some editor commands, the occurrence of ап error has а well defined meaning, i.e, they use | 
errors to branch on, as cond uses NIL and non-NIL. For example, an error condition in a location 
specification may simply mean "not this one, try the next." Thus the location specification | 

(IPLUS (E (OR (NUMBERP (££ 3)) (ERROR!)) T)) specifies the first IPLUS whose 
second argument is a number. The IF command, by equating NIL to error, provides a more 
natural way of accomplishing the same result. Thus, an equivalent location specification is (IPLUS _ 
(ТЕ (NUMBERP (## 3)))). 


The IF command can also be used to select between two alternate lists of commands for execution. 


(IF x coms; coms») If eval[x] is true, execute coms); if eval[x] causes an error or is 
equal to NIL, , execute coms». 


For example, the command (IF RENE T) NIL (P)) will print the current expression 
provided the input buffer is empty. 


7 because NIL as a command is a no-op, see page 9.52. 


78 — Thus IF is equivalent to (COMS (CONS (QUOTE COMSQ) (COND 
((CAR (NLSETQ (EVAL X))) СОМ51) 
(T C0MS2)))). 
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(IF x coms) | | if eval[x] is true, execute соту; otherwise generate an error. | 


(LP . coms) | repeatedly executes coms, a list of commands, until an error occurs. ` 


For example, (LP F PRINT (N T)) will attach a T at the end of every print expression. (LP F 
. PRINT (ТЕ (## 3) NIL ((N T)))) will attach a T at the end of each print expression which - 
does not already have a second argument. 


When an error occurs, LP prints n OCCURRENCES. where n is the 
number of times coms was successfully executed. The edit chain is 
left as of the last complete successful execution of coms. | 


(LPQ . coms) same as LP but does not print the message n OCCURRENCES, | 


In order to prevent non-terminating loops, both LP and LPQ terminate when the number of 
iterations reaches maxloop, initially set to 30.89 Since the edit chain is left as of the last successful 
completion of the loop, the user can simply continue the LP command with REDO (Section 22). 


(SHOW . x) . x is a list of patterns. SHOW does а ІРО printing all instances of 
| | the indicated expression(s) e.g. (SHOW FOO (5ЕТО ЕТЕ &)) will 
print all FOO’s and all (SETQ FIE &)’s. Generates an error if 

there aren’t any instances of the expression(s). | A 


(EXAM . x) | like SHOW except calls the editor recursively (via the TTY: 
Ға | = command described on page 9.49) on each instance of the 
indicated espression(s) so that the user can examine and/or change 

them. 


(ORR coms; ... coms,) ORR begins by executing coms), a list of commands. If no error 
| occurs, ORR is finished. Otherwise, ORR restores the edit chain to 
its original value, and continues by executing coms», etc. If none 
of the command lists execute without errors, i.c., the ORR "drops 
off the end", ORR generates an error. Otherwise, the edit chain is 
left as of the completion of the first command list which executes 
without an error. _ 


79 ie. the form (## 3) will cause an error if the edit command 3 causes an error, thereby selecting ((N T)) as the 
list of commands to be executed. The IF could also be written as (IF (СООК (##)) NIL ((М T))). 


80 maxloop can also be set to NIL, which is equivalent to setting it to infinity. 


81. NIL as a command list is perfectly legal, and will always execute successfully. Thus, making Ше last "argument" to 


ORR be NIL will insure that the ORR never causcs an error, Any other atom is treated as (atom), 1.е., the above 
example could be written as (ORR NX INX NIL). 
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Соттапаз That Test | 


For example, (ORR (NX) (INX) NIL) will perform a NX, if possible, otherwise а !NX, if 


possible, otherwise do nothing. Similarly, DELETE could be written as 


(ORR (UP (1)) (BK UP (2)) (UP (: NIL))). 


9.8 MACROS 


Many of the more sophisticated branching commands in the editor, such as ORR, IF, etc., are 


most often used in conjunction with edit macros. The macro feature permits the user to define | 


new commands and thereby expand the editor's repertoire, or redefine existing commands. 
Macros are defined by using the M command. 


(Mc. coms) For c an atom, M defines c as an atomic command.®3 Executing С is 


then the same as executing the list of commands coms. 


For example, (M BP BK UP Р) will define BP as an atomic command which does three things, a 


BK, and UP, and a P. Macros can use commands defined by macros as well as built in commands 
in their > definitions. For example, suppose 7 1$ defined by 


(M Z -1 (IF (READP T) a (P))), ie. Z does a 1, and then if nothing has been typed, a 
Now can . define = Zl by 
Си 22 -1 7), and ZZZ by (M. IM -1 -1 Z) or (M ZZZ -1 77). 


Macros can also define list commands, 1.е., commands that take arguments. 
(М (с) (argy ... аге). coms) c an atom. M defines c as a list command. preii се... е) 


is then performed by substituting ej Юг агру,.. eg for arg, 
throughout coms, and then executing coms. | 


For example, we could define a more general BP by (M (ВР) (М) (ВК М) UP P). Thus, (ВР 


3) would perform (BK 3), followed by an UP, followed by а Р. 


A list command can be defined via a macro so as to take a fixed or indefinite number of 
"arguments", as with spread vs. nospread functions. The form given above specified a macro with 
a fixed number of arguments, as indicated by its argument list. If the “argument list" is atomic, 
the command takes an indefinite number of arguments.B4 | 


(М (с) arg . coms) c, arg both atoms, defines c as a list command. Executing 
(с ет... ед) is performed by substituting (еј -- ед), i.e., cdr of the 
| | command for arg throughout coms, and then executing coms. 


For example, the command 2ND, page 9.20, can be defined as а macro by 
(М (2ND) X (ORR ((LC . X) (ІС. X)))). " | 


82 To refer to the original definition of a built-in command when redefining it via а macro, use the ORIGINAL 
command described below. 

83 If a macro is redefined, its new definition replaces its old. 

84 


Note parallelism to EXPR's and EXPR®’s, 
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Note that for all editor commands, "built in" commands as well as commands defined by macros, 
atomic definitions and list definitions are completely independent. In other words, the cxistence of 
ап atomic definition for с in no way affects the treatment of с when it appears as car of a list 
command, and the existence of a list definition for с in no way affects the treatment of с when it 
appears as an atom. In particular, с can be used as the name of cither an atomic command, or a 


list command, or both. In the latter case, two entirely different definitions can be used. 


` Note also that once с is defined as an atomic command ма a macro definition, it will not be 


searched for when used in a location specification, unless it is preceded by an F. Thus (INSERT 
-- BEFORE BP) would not search for BP, but instead perform a BK, and UP, and a P, and 
then do the insertion. The corresponding also holds true for list commands. 


Occasionally, the user will want to employ the S command іп a macro to save some temporary _ 
result. For example, the SW command could be defined as: | | 


(M (SW) (мм) (NTH М) (S FOO 9 MARK 0 (NTH M) (S FIE 1) 
(I 1 F00) ее (11 FIE)) 


Since this version of SW sets foo and fie, using SW may have undesirable side effects, especially 
when the editor was called from deep in a computation, we would have to be careful to make up 
unique names for dummy variables used in edit macros, which is bothersome. Furthermore, it 
would be impossible to define a command that called itself recursively while setting free variables. 
The BIND command solves both problems. | | | 


(BIND . coms) | . binds three dummy variables #1, #2, #3, (initialized to NIL), and 
Lx ! then executes the edit commands coms. Note that these bindings 
. are only in effect while the commands are being executed, and that 
BIND can be used recursively; it will rebind #1, #2, and #3 each 
time it is invoked. 


Thus we could now write SW safely as: 


(M (SW (N M) (BIND (NTH N) (S #1 1) MARK 0 (NTH M) (S 42 1) 
(I 1 #1) се (I 1 #2)))). 


User macros are stored on a list usermacros. The file package command USERMACROS (Section 
14), is available for dumping all or selected user macros. 


(ORIGINAL . coms) executes coms without regard to macro definitions. Useful for 
redefining a built in command in terms of itself, i.e. effectively 
allows user to "advise" edit commands, 


A more elcgant definition would be: | 
(М (SW) (мм) (NTH М) MARK 0. (NTH М) (5 ЕТЕ 1) G 1 (## – 1)) «+ (11 FIE)), 
but this would still use one free variable. 


86 BIND is implemented by (PROG (#1 #2 #3) (EDITCOMS (CDR СОМ))) where com corresponds to the BIND 
command, and editcoms is an internal editor function which executes а list of commands. 
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9.9 MISCELLANEOUS COMMANDS 


9.9.1 COMMANDS FOR LEAVING THE EDITOR 


OK exits from the editor 


STOP exits from the editor with an error. Mainly for use in conjunction 
with TTY: commands that the user wants to abort. 


Since all of the commands in the editor are errorset protected, the user must exit from the editor 
ма a command.®’ STOP provides a way of distinguishing between a successful and unsuccessful 
(from the user's standpoint) editing session. For example, if the user is executing (MOVE З ТО 
AFTER COND TTY:), and he exits from the lower editor with an OK, the MOVE command will 
then complete its operation. If the user wants to abort the MOVE command, he must make the 
TTY: command generate an error. He does this by exiting from the lower editor with a STOP 
command. In this case, the higher editor's edit chain will not be changed by the TTY: command. 


SAVE | exits from the editor and saves the "state of the edit" on the 
| property list of the function or variable being edited under the _ 
property EDIT-SAVE. If the editor is called again on the same 
structure, the editing is effectively "continued," i.e. the edit chain, 

mark list, value of unfind and undolst are restored. - MN 


For example: 


ер 

(NULL X) 

*F COND P 

(COND (& &) (T &)) 
*SAVE 

FOO 


<ЕОТТЕ (FOO) 

EDIT 

*р 

(COND (8 8) (T &)) 
*\ P 

(NULL X) 

[| 


ЗАМЕ is necessary only if the user is cditing many different expressions; ап exit Кот the editor via 


87 


Or by typing а control-D. STOP is preferred even И the user is са пр at the evalat level, as it will perform the 
necessary "wrapup" to insure that the changes made while editing will be undoable (sce Section 22). 
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OK always saves the state of the edit of that call to the editor.88 Whenever the editor is entered, it 
checks to see if it is editing the same expression as the last one edited. In this case, it restores Ше 
mark list, the undolst, and scts unfind to be the edit chain as of the previous exit from the editor. 


For example: 


«ЕРІТЕ (200) 


«ЕПІТЕ( 200) 

EDIT 

*p Ж | 
(LAMBDA (X) (PROG & & LP & & & &)) 


*р 

(COND & 4) 
“ОК 

оо 

| апу number of lispx inputs 
except for calls to the editor 


EDIT 


"Фр 


(LAMBDA (X) (PROG & 8, LP & 8: 8, &)) 
*\ р | 

(СОМО & &) 

* 


Furthermore, as a result of the history feature (section 22), if the editor is called on the same 
expression within a certain number of lispx inputs? the state of the edit of that expression is 
restored, regardless of how many other expressions may have been edited in the meantime. 
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on the property list of the atom EDIT, under the property name LASTVALUE. OK also remprops EDIT-SAVE from 


the property list of the function or variable being edited. 
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Namely, the size of the history list, initially 30, but it can be increased by the user. 
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For example: 


«ЕРІТЕ ( 200) 
EDIT 
# 


«р | 

(COND (84) (% %) (4) (T &)) 

“ОК 

ЕОО | 

E less than 30 lispx inputs, including editing 


-EDITF(FOO) 

EDIT 

*\ P 

(COND (& &) (& &) (&) (T &)) 


Thus the user can always continue editing, including undoing changes from a previous editing 
session, if 


(1) Мо other expressions have been edited since that session;? or 
(2) That session was "sufficiently" recent; or 


(3) It was ended with a SAVE command. 


9.9.2 NESTED CALLS TO EDITOR 


TTY: calls the editor recursively. The user can then type in commands, 
and have them executed. The TTY: command is completed when 
the user exits from the lower editor. (see OK and STOP below). 


The TTY: command is extremely useful. It enables the user to set up a complex operation, and 
perform interactive attention-changing commands part way through it. For example the command 
(MOVE 3 TO AFTER COND 3 P TTY:) allows the user to interact, in effect, within the MOVE 
command. Thus he can verify for himself that the correct location has been found, or complete 
the specification "by hand." In effect, TTY: says "I'll tell you what you should do when you get 
there." | 


The TTY: command operates by printing TTY: and then calling the editor. The initial edit chain 
in the lower editor is the onc that existed in the higher editor at the time the TTY: command was 
entered. Until the user exits from the lower editor, any attention changing commands he exccutes 


Since saving takes place at exit time, intervening calls that were aborted via control-D or exited via STOP will not 
affect the editor's memory of this last session. | 
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only affect the Јомег editor’s edit chain. 91 When the ШЕ command finishes, the lower editor’s 
edit chain becomes the edit chain of the higher editor. | | 


+ EF | "S calls editf on car of current expression. 
+ EV,EP | calls editv, editp on car of current expression. 


. 9.9.3 MANIPULATING THE CHARACTERS OF АМ ATOM OR STRING 


RAISE : is ап edit macro defined as UP followed by 
i (I 1 (U-CASE (## 1))), ie, it raises to upper-case the 
current expression, or if a tail, the first element of the current 


expression. 
LOWER са » A Similar to RAISE, except uses 1-сазе, 
САР = First does a RAISE, and then lowers АП but the first character, i.e. 


the first character is left capitalized. 


Note: RAISE, LOWER, and CAP are all no-ops if the corresponding atom or String is already in 


that state. 
. (RAISE x) _ equivalent to (I R (L-CASE x) x), ie, changes every lower-case . 
ох to upper-case in the current expression. 
(LOWER x) | - similar to RAISE, except performs (I R x (L-CASE x)). 


„Кое in both (RAISE x) and (LOWER x), x is typed in in upper case. 
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Of course, if the user. performs any structure modification commands while under a TTY: command, these will 
modify the structure in both editors, since it is the same structure. 
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REPACK | — Permits the "editing" of an atom or string. 
Бог example: 


*р | 
... "THIS IS А LOGN STRING") 
*REPACK 

“EDIT | 
р | | | | 

(ТНТ 54 IS% A% LOGN% STRING) 
"(ои G М) 

“ОК 

"THIS IS A LONG STRING" 92 

E d 


REPACK operates by calling the editor recursively on unpack of the current expression, or if it is a 
list, on unpack of its first element. If the lower editor is exited successfully, i.e., via OK as opposed 
to STOP, the list of atoms is made into a single atom or string, which replaces the atom or string 
being ’repacked.’ The new atom or string is always printed. 


(REPACK @) | does (LC . @) followed by REPACK, eg. (REPACK THIS$). 


9.9.4 MANIPULATING PREDICATES AND CONDITIONAL EXPRESSIONS 


JOINC is used to join two Web |  COND's sto then | 
e.g. (COND clause; clausey) followed by (COND clause; clause4) . 
becomes (COND clause élause, clause3 clause, ). JOINC does an | 
(F COND T) first so that you dont have to be at the first COND. 


(SPLITC x) splits one COND into two. x specifies the last claas in the first 
COND, e.g. (SPLITC 3) | | Splits 
(COND clause, clause? clause; clause4) into (COND clause, clause») 
(COND clause4 clausc4). Uses generalized NTH command, so that x 
does not have to be a number, e.g., the user can say 
(SPLITC RETURN), meaning split after the clause containing 
RETURN.  SPLITC also does an (F COND T) first. 


NEGATE negates current expression, ie. performs (MBD NOT), except is - 


+ 

smart about simplifying. For example, if current expression is: + 

(OR (NULL X) (LISTP X)), NEGATE would change it to + 

(AND X (NLISTP X)). NEGATE is implemented via the function + 

negate. + 

SWAPC = takes a conditional expression of the form (COND (A В)(Т C)) + 


92 Note that this could also have been accomplished by (R $GN$ $NG$) or simply (RC GN NG). 
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and rearranges it to ап equivalent (COND ((NOT А) C)(T B)), 
or (COND (A B) (C D)) to 
(COND ((NOT A) (COND (C D))) (T B)). | 
. SWAPC is smart about negations (uses NEGATE) and simplifying 
 conds. It always produces an equivalent expression. It is useful for 
those cases where one wants to insert extra clauses or tests. 
9.9.5 HISTORY COMMANDS IN THE EDITOR 
As described in Section 22, all of the user's inputs to the editor are stored on edithistory, the 
editor's history list, and all of the programmer's assistant commands for manipulating the history | 
list, ер. REDO, USE, FIX, NAME, etc., are available for use on events on edithistory. In | 
addition, the following four history commands are recognized specially by the editor. They always 
operate on the last, ie. most recent, event. 
DO com » allows the user to supply the command name when it was 
omitted? 

For example, suppose Ше user wants to perform (-2 (SETQ X (LIST Y Z))) but instead 
types just (SETQ X (LIST Y Z)). The editor will type SETQ ?, whereupon the user can type 
DO -2. The effect is the same as though the user had typed FIX, followed by (LI 1), (-1 - 
2), and OK, i.e., the command (-2 (SETQ X (LIST Y 7))) is executed. DO also works if the 
command is a line command. | 
IF. | same as DO F. 

. In the case of ІР, the previous command is always treated as though it were a line command, e. 2., 

if the user types (SETQ X 4) and then ІР, the effect is the same as though he had typed 
F (SETQ X &), not (F (SETQ Х &)). 

ЈЕ same as DO Е. 

ІМ $ате а5 00 М. 

9.9.6 MISCELLANEOUS 

NIL | |  . unless preceded by Е ог ВЕ, is always a по-ор. Thus extra right 
2 ғ” | | parentheses or square brackets at the cnds of commands аге 

ignored. 
есі | | Clispifies current expression. See Scction 23. 
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USE is useful when a command name is Incorrect. 
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DW 


| GET* 


(* . x) 


GETD 


Miscellaneous Commands 


Dwimifies current expression. See Section 17 and 23. 


If the current expression is a comment pointer (sce Section 14), 
reads in the full text of the comment, and replaces ie current 
expression by it. 


x is the text of a comment. * ascends the edit chain looking for a- 


"safe" place to insert the comment, e.g., іп a cond clause, after а 
prog statement, etc., and inserts (* . x) after that point, if possible, 
otherwise before. For example, if the current expression is 
(FACT (SUB1 N)) in | 
[COND ((ZEROP М) 1) 

(Т (ІТІМЕЅ М (FACT (5081 N] 


(% CALL FACT RECURSIVELY) would insert | 
(% CALL FACT RECURSIVELY) before the itimes expression.”4 


ж does not change the edit chain, but unfind is set to where the 
comment was actually inserted. 


essentially " 'expands" the current expression in line: (1) if (car of) 
the current expression is the name of a macro, expands the macro 
in line; (2) if a clisp word, translates the current expression and 


replaces it with the translation; (3) if car is the name of a 


function? ^ substitutes the argument expressions for the 
corresponding argument names in the body of the definition and 
replaces the current expression with the result; (4) if car of the 
current expression is an open lambda, substitutes the arguments for 
the corresponding argument names in the body of the lambda, and 
then removes the lambda and argument list. 


(MAKEFN (fn . actualargs) arglist nl n2) 


the inverse of GETD: makes the current expression into a function. 
fn is the function name, arglist its arguments. The argument names 
are substituted for the corresponding argument values in actualargs, 
and the result becomes the body of the function definition for fn. 
The current expression is then replaced with (fn . actualargs)..- 


For example, if the current expression is (COND ((CAR X)(PRINT Y T))(T (HELP))), then 
(MAKEFN (FOO (CAR X) Y) (A B)), will define FOO as 
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If inserted after the itimes, the comment would then be (incorrectly) returned as the value of the cond. However, if 


the cond was itself a prog statement, and hence its value was not being used, the comment could be (and would be) 
inserted after the itimes expression, 
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for which the editor can obtain a symbolic definition, either in-core or from a file. 
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+ (LAMBDA (A В) (COND (A (PRINT В Т)) (Т (HELP)))) and then replace the current 
+ expression with (FOO (CAR X) Y). | 


If nl and n2 are supplied, (М1 THRU N2) is used rather than the 
current expression; if just nl is supplied, (М1 THRU -1) is used. 


If arglist is omitted, MAKEFN will make up some arguments, using 
elements of actualargs, if they are literal atoms, otherwise arguments 
selected from (X Y Z A B C ...), avoiding duplicate argument 
names. 


++++ ++ 


(МАКЕ argname exp) makes the value of argnam e be ex exp in the call which is the current | 
| | expression, i.e. а ?— command following а MAKE will always pant 
argname — exp. For example: | 


JSYS[N;AC1,AC2,AC3, RESULTAC] 
*(MAKE N 10) 

"(МАКЕ RESULTAC 3) 

*р 

(JSYS 10 NIL NIL NIL 3) 


++ + + + + + + +++ 
# 
~) 
u 


quotes current expression, i.e. MBD QUOTE. 


-- 
«> 


р deletes current expression, then Бш: new current expression, 1.е. 


(:) I P. 


++ 


9.10 UNDO 


Each command that causes structure modification automatically adds an entry to the front of 
undolst that contains the information required to restore all pointers that were changed by that 
command. | 


UNDO _ | undoes the last, i.e., most recent, structure modification command 
| that has not yet been undone,” and prints the name of that 
command, е.р., MBD UNDONE. The edit chain is then exactly what 


96 Since UNDO and | UNDO cause structure modification, they also add an entry to undolst. However, UNDO and ! UNDO 
entries are skipped by UNDO, e.g.. if the user performs an INSERT, and then an MBD, the first UNDO will undo the | 
MBD, and the second will undo the INSERT. However, the user can also specify precisely which commands ће wants 
undone by identifying the corresponding entry on Ше history list as described in Section 22. In this case, һе can 
undo an UNDO command, e.g., by typing UNDO UNDO, or undo а | UNDO command, ог undo a command other than 
that most recently performed. 
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it was before the "undone" command had been performed.’ If 
there are no commands to undo, UNDO types NOTHING SAVED. 


| UNDO undoes all modifications performed during this editing session, i.e. 
| this call to the editor. As each command is undone, its name is 
printed a la UNDO. If there is nothing to be undone, | UNDO prints 

NOTHING SAVED. | | 


Whenever the user continues an editing session as described оп page 9.47-49, the undo information. 
of the previous session is protected by inserting a special blip, called an undo-block, on the front ог 
undolst. This undo-block will terminate the operation of a ! UNDO, thereby confining its effect to 
the current session, and will similarly prevent an UNDO command from operating on commands 
executed in the previous session. 


Thus, if the user enters the editor continuing a session, and immediately executes an UNDO or 
IUNDO, the editor will type BLOCKED instead of NOTHING SAVED. Similarly, if the user executes 
several commands and then undoes them all, another UNDO or !UNDO will also cause BLOCKED to 
be typed. 


UNBLOCK removes an undo-block. If executed at а non-blocked state, i.e., if 
UNDO ог !UNDO could operate, types NOT BLOCKED. 


TEST adds an undo-block at the front of undolst. 


Note that TEST together with !UNDO provide a "tentative" mode for editing, 1.е., the user can 
perform a number of changes, and then undo all of them with a single | UNDO command. 


UNDO ¢ ¢ is an event specification (Section 22). Undoes the indicated event 
| on the history list. In this case, the event does not have to be in the 

current editing session, even if the previous session has not been 

unblocked as described above. However, the user does have to be 

editing the same expression as was being edited in the indicated | 

event. 


37 Undoing an event containing an I, E, or S command will also undo the side effects of the evaluation(s), e.g., 
undoing (I 3 (/NCONC FOO FIE)) will not only restore the 3rd element but also restore Ғ00. Similarly, undoing 
an S command will undo the set. Sce discussion of UNDO in Section 22. (Note that if the I command was typed 
directly to the editor, /NCONC would automatically be substituted for NCONC as described in Section 22.) 
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If the expressions differ, the editor types the warning message "different expression" , and does not undo 
the event. The editor enforces this to avoid the user accidentally undoing a random command m giving the wrong 
cvent spccification. 
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9.11 EDITDEFAULT 


Whenever a command is not recognized, i.e., is not "built іп" or defined as a macro, the editor 
calls an internal function, cditde fault to determine what action to take.?? If a location specification 
is being гоо ап internal flag informs editdefault to treat the command as though it had been | 
preceded by an F | 


If the command is а tist, an attempt is made to perform spelling correction on car of the 
соттапӣ100 using editcomsl, a list of all list edit commands. If spelling correction is 


successful? the correct command name is rplacacd into the command, and the editor continues 


by . executing the command. In other words, if the user types 
(LP F PRINT (MBBD AND (NULL FLG) )). only one spelling correction will Бе necessary to 
change MBBD to MBD. If spelling correction is not successful, an error is generated. 


If the command is atomic, the procedure followed is a little more elaborate. 


1) If the command is one of the list commands, Те. a member of editcomsl, and there, is 
additional input on the same terminal line, treat the entire line as a single list command.t 
Thus, the user may omit parentheses for any list command typed in at the top level (provided 
the command is not also an atomic command, e.g. NX, BK). For example, 


"P 
(COND (8 в) (T &)) 
*XTR 3 2] 

*MOVE 5% AFTER LP 


If the command is on the list editcomsl but no additional input is on the terminal line, an 
error is generated, e.g. 


"D o 
(COND (& &) (T &)) 
*MOVE 


MOVE ? 
* 


99 Since editdefault is part of the edit block, the user cannot advise or redefine it as a means of augmenting or 
extending the editor. However, the user can accomplish this via edituserfn. If the value of the variable edituserfn is 
T, editdefault calls the function edituserfn giving it the command as an argument. If edituserfn returns a non-NIL 
value, its value is interpreted as a single command and executed. Otherwise, the error correction procedure described 
below is performed. 

100 — inless dwimflg = NIL. See Section 17 for discussion of spelling correction. 

101 When a macro is defined via the M command, the command name is added to editcomsa or editcomsl, depending on 
whether it is an atomic or list command. The prettydef command USERMACROS (Section 14), is aware of this, and 
provides for restoring editcomsa and cditcomsl. | 

102 Throughout this discussion, if the command was not typed in directly, the user will be asked to approve the spelling 
correction. See Section 17. 
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The line is read using readline (Section 14). Thus the line can be terminated by a. square bracket, ог by a сапаре 
return not preceded by a space. 
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Editdefault 


If the command is on editcomsl, and not typed in directly, e.g., it appears as one of the 
commands in a LP command, the procedure is similar, with the rest of the command stream 
at that level being treated as "the terminal line", e.g. | 


(LP Е (COND (T &)) XTR 2 2),1% 


If the command was typed іп and the first character іп (һе command is ап 8, treat the 8 as a 
mistyped left parenthesis, and and the rest of the line as the arguments to the command, e.g., 


ер 

(COND (& 8) (T &)) 

*8-2 (Y (RETURN 2))) 
=(-2 

жр 

(COND (Y 8) (& &) (T &)) 


If the command was typed in, is the name of a function, and is followed by NIL or a list car- 
of which is not an edit command, assume the user forgot to type E and means to apply the 
function to its arguments, type -E and the. function name, and perform the indicated 
computation, e.g. | | 


*BREAK(FOO) 
=E BREAK _ 
(FOO) 

ж 


If the last character in the command is P, and the first п-1 characters comprise a number, 
assume that the user intended two commands, e.g., 


*р 

(COND (& 8) (T &)) 
*0P 

=0 P 

(SETQ X (COND & &)) 


Attempt spelling correction using editcomsa, and if successful? execute the corrected 
command. | 


Otherwise, if there is additional input on the same line, or command stream, spelling correct 
using editcomsl as a spelling list, e.g., 


Note that if the command is being executed in location context, editdefault does not get this far, e.g., (MOVE ТО 
AFTER COND XTR 3) will search for XTR, not execute it However, (MOVE TO AFTER COND (XTR 3)) will | 
work. | 


See footnote on page 9,57. 
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*MBBD SETQ X 
=MBD 


* 


Otherwise, generate an error. 


9.12 EDITOR FUNCTIONS 


nl | | ee ИС За 
nlambda, nospread function for editing a function. пате is the 


name of the function, com), com», .., com, (optional) edit 
commands. | 


The value of editf is name. 


In the most common case, name is an expr, and ейі simply performs 
putd[name;edite[getd[name];list[com ;com);...;com,,];name;FNS]]. However, if name is an | 


expr by virtue of its being broken or advised, and 


(la) the original definition is also an expr, then the broken/advised definition is given to 
edite to be edited (since any changes there will also affect the original definition 
because all changes are destructive). However, a warning message is printed to alert 
the user that he must first position himself correctly before he can begin typing 
commands such as (-3 --), (N --), ек. 


— (1b) the original definition is not an expr, and there is no EXPR property, and the file 


package "knows" which file name is contained in (see discussion of editloadfns? below), 
then the expr definition of name is loaded onto its property list as described in (3) 
below, and proceeds to (lc) otherwise a warning message is printed, and the edit 
proceeds, e.g., the user may have called the editor to examine the advice on a subr. 


(1c) the original definition is not an expr, and there is an EXPR property, then the function 
| is unbroken/unadvised (latter only with user's approval, since the user may really want | 


to edit the advice) and proceed as in (2). 


If name is not an expr, but has an EXPR property, editf prints PROP, and performs 
edite[getprop[name;EXPR];list{com :сот»;...;сот „|;пате;РКОР]. In this case, if the edit 
completes and no changes have been made, edite prints NOT CHANGED, SO NOT UNSAVED. 
If changes were made, but the value of dnameflg is PROP, edite prints CHANGED, BUT МОТ 
UNSAVED. Otherwise if changes were made, edite prints UNSAVED and docs an unsavedef. 


if name is neither an expr nor has an EXPR property, and the file package (see Section 14) 
"knows" which file name is contained in (sce discussion of editloadfns? below), the expr 


definition of name is automatically loaded (using loadnames) onto its property list, and / 
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Editor Functions 


proceed to (2) above.! In addition, if пате is a member of a block (sce Section 18), the user 
will be asked whether he wishes the rest of the functions in the block to be loaded at the 
same time,107 


If name is neither an expr nor as an EXPR property, but it does have а definition, editf 
generates an name NOT EDITABLE error. 


If name is neither defined, nor has an EXPR property, but its top level value is a list, editf 
assumes the user meant to call editv, prints =EDITV, calls editv and returns. Similarly, if 
name has a non-NIL property list, editf prints =EDITP, calls editp and returns. | 


If name is neither a function, nor has an EXPR property, пог a top level value that is a list, 


nor a non-NIL property list, editf attempts spelling correction. using the Spelling list 


userwords,!8 and if successful, goes back to (1). | 


Otherwise, editf generates an name NOT EDITABLE error. 


In all cases, if a function was edited, and changes were ‚ made, the function is time- stamped (by 
edite), which consists of inserting a comment of the form (* xxx date), where ххх are (һе user’s 
initials. If the function was already time-stamped, then only the date is changed.’ 


editfns[name;com, ;com»;...;com 
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operations on several functions. name is evaluated to obtain a list 


Because of the existence of the file map (see Section 14), this operation is extremely fast, essentially requiring only 
the time to perform the READ to obtain the actual definition. 


The editor's behaviour in case (3) is controlled by the value of editloadfnsflg, which is a dotted pair of two flags, the 


first of which (ie, car of editloadfnsflg) controls the loading of the function, and the second the loading of the 


block. A value of NIL for either flag means "load but ask first," a value of T means "don't ask, just do it" and 
anything else means "don't ask, don't do it." The initial value of editloadfnsflg is (T), meaning load the function 
without asking, ask about loading the block. 


Unless dwimflg=NIL. Spelling correction is performed using the function misspelled?. If name=NIL, misspelled? 
returns the last "word" referenced, e.g., by defineq, editf, prettyprint etc. Thus if the user defines foo and then types 
еди, the editor will assume he meant foo, type =FOO, and then type EDIT. See Section 17. 


xxx is the value of the variable initials. After greeting, or following a sysin, the function setinitials is called. setinitials 
searches initialslst, a list of elements of the form (username . initials) or (username firstname initials). If the user's 
name is found, initials is set accordingly. If the user's name is not found on initialslst, initials is set to the value of 
defaultinitials, initially edited:. Thus, the default is to always time stamp. To suppress time stamping, the user 
must either include an entry of ihe form (username) on initialslst, or set defaultinitials to NIL before greeting, i.e. in 
his user profile, or else, a/ter greeting, explicitly set initials to NIL. Е 


The following three functions may be of use for specialized applications with respect to time-stamping: 
fixcditdate[expr] which, given a lambda expression, inserts or smashes a time-stamp comment; editdate?[comment] 
which returns T if comment is a time stamp: and editdate[oldate;initls] which returns a new time-stamp comment. If 
oldate is a time-stamp comment, it will be reused. | 
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Al льва, nospread function, used to perform the same editing 
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of functions! соту, com», ..., com, are е (optional) edit commands. 
editfns maps down the list of functions; prints the name of each 
function, and calls the editor (via editf) on that function, 


For example, EDITFNS(FOOFNS (В ЕТЕ FUM)) will change every ЕТЕ to FUM in each of the - 


functions on foofns. 


The call to the editor is errorset protected, so that if the editing of 
one function causes an error, editfns will ыны to the next 
function.43 


Thus in the pave example, if one of the functions did not contain a FIE, the R command mould 
cause an error, but editing would continue with the next function. | | 


The value of editfns is NIL. - 


The function editcallers provides a way of rapidly searching a file | or entire set. of files, even files 
not loaded into Interlisp or "noticed" by the file package, for the appearance of one or more key 
words (atoms) anywhere in the file, 


editcallers[atoms; files;coms] . uses ffilepos to search the file(s) files for occurrences nr the atom(s) 

| atoms. It then calls edite on each ch of those objects, > performing 

the edit commands coms. If coms=NIL, then (EXAM . ATOMS) is 

used. Both atoms and and files may be single atoms. If files is NIL, 
filelst is used. Ele Elements on on atoms may contain < esc ? S. 


editcallers prints the name : of each. file : as it matches it, d when it 
finds an occurrence of one of atoms, it prints out either the name 


function definition, it prints out the byte position that the atom was 
found. 


editcallers will read in and use the filemap of the file. In the case 
that the editor is actually called, editcallers will loadfrom the file if 
the file has not previously been noticed. 


111 
functions to be edited. 


112 ie, the definition of editfns might be: 
[MAPC (EVAL (CAR X)) (FUNCTION (EAE EY) | 
(APPLY (QUOTE ЕРІТЕ) 
(CONS (PRINT Y T) (сов Х1 


113 


In other words, in the above example, only those functions which contained а ЕТЕ, i.e., only those actually changed, 
would be unsaved. | 


editcallers was written by L. M. Masinter. 


Герун à MÀ 


made, putdef is called to storc the changed object. 
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of the containing function or, if the atom occurred outside a 


If name is atomic, and its s value is not a list, and it is ine name of a file, тепала will be е. as the list of | 


In particular, if an error occurred while editing a function via its EXPR property, the function would not be unsaved, 


Editor Functions 


findcallers[atoms; files] like editcallers, except does not call the editor, but instead simply 
| returns the list of files that contain one of atoms. 


editv[name;com ;com»;...;comj] 


nlambda, nospread function, similar to editf, for editing values. | 


If name is а list, it is evaluated and its value given to edite, eg. 
EDITV((CDR (ASSOC (QUOTE FOO) DICTIONARY) ))). In this case, the value of editv is T. 


However, for most applications, name is a variable name, i.e., atomic, as in EDITV(F 00) . If the 
value of this variable is NOBIND, editv checks to see if it is the name of a function, and if so, 


assumes the user meant to call са prints = "ЕРИ, calls editf and returns. Otherwise, edity | 


attempts spelling correction using the list userwords.1! Then editv will call edite on the value of 
car[editvx] (or the corrected spelling thereof), and type — VARS. Thus, if the value of foo is NIL, 


and the user performs (EDITV FOO), no spelling correction will occur, since foo is the name ofa- 


variable in the user's system, i.e., it has a value. However, edite will generate an error, since foo's 
value is not a list, and hence not editable. If the user performs (ЕРІТУ #2000), where the value 
of [000 is NOBIND, and foo is on the user's spelling list, the spelling corrector will correct FOOO to 
FOO. Then edite will be called on the value of foo. Note that this may still result in an error if 
the value of foo i is not a list. 


The value of editv is the name of the variable whose value was edited. 


editp[name;com; ;com»;...;:comg] 


nlambda, nospread function, similar to editf for editing property - 
lists. If the property list of name is NIL, editp attempts spelling | 


correction using userwords. Then editp calls edite on the property 


list of пате, (or the corrected spelling thereof), with 


type=PROPLST. When (if) edite returns, editp calls setproplist on 
name with the value returned. . 


The value of editp is the atom whose property list was edited. 


edite[expr;coms;atm;type;ifchangedfn] | 
edits the expression, expr, by calling ей on list[expr] and 
returning the last element of the value returned by editl. Generates 
an error if expr is not a list. 


atm and type are for use in conjunction with the file package. If 
supplied, atm is the name of the object that expr is associated with, 
and type describes the association. (ie. type corresponds to the 
type argument of newfile?.) For example, if expr is the definition of 
foo, atm = РОО and type —FNS. When edite is called from editp, 
expr is the property list of atm, and type— PROPLST, etc.. 


edite calls edit] to do the editing (described below). Upon return, if 


16 Unless dwimflg = NIL. Misspelled? is also called if car[editvx] is NIL, so that EDITV() will edit lastword. 
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both atm and type are non-NIL, addspeil is called to add atm to 
the appropriate spelling list. Then, if expr was changed, and the 
value of ifchangedfn is not NIL, the value of ifchangedfn is applied 


to the arguments atm, expr, type, and a flag which is Т for normal | 


edits from editor, NIL for calls that were aborted via control-D or 
STOP. Otherwise, if expr was changed, and the value of 
ifchangedfn is NIL, and type is not NIL, newfile? (see Section 14) 
is called on, atm and type. edite uses resetsave to insure that 
ifchangedfn/newfile? are called if any change was made even if 
editing is subsequently aborted via control-D. (In this case, i 
fourth Argument to ifchangedfn wil be NIL.) 


она с coms;atm;mess;editchanges] 


118 


120 


.editl!5 is the editor. Its first argument is the edit chain, and its 


value is an edit chain, namely the value of 1 at the time editl is 
ехкед.19 


coms is an optional list of commands. For interactive editing, coms | 
is NIL. In this case, editl types EDIT and then waits for input 


from terminal? АП input is done with editrdtbl as а readtable. 
Exit occurs only via an OK, STOP, or SAVE command. 


If coms is not NIL, no message is typed, and each MN of 


coms is treated as a command and executed. If an error occurs in- 
the execution of one of the commands, no error message is printed, | 


the rest of the commands are ignored, and editl exits with an error, 
ie. the effect is the same as though a STOP ОР command had been 
executed. If all commands execute successfully, edit! returns the 
current value of 1. 


atm is optional. On calls from editf, it is the name of the function 
being edited; on calls from editv, the name of the variable, and 
calls from editp, the atom whose property list is being edited. The 

property list of atm is used by the SAVE command for saving the 
state of the edit. Thus SAVE will not save anything if atm=NIL, 

i.e., when editing arbitrary expressions via edite or edit! directly. 


editchanges is used for communicating with edite. 


For type=FNS or type= PROP, i.e. calls from editf, edite performs some additional operations as described earlier 


under editf. 


edit-ell, not edit-one. 


1 is а specvar, and so can be examined or set by edit commands. For example, t is equivalent to 


|. (E (ФЕТО L (LAST L)) Т). However, the user should only manipulate or examine | directly as a last resort, 
and then with caution, 


If mess is not NIL, сай! types it instead of EDIT. For example, the TTY: command is На (5ЕТО L | 
(EDITL L NIL NIL (QUOTE TTY:))). 
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editlO[l;coms;mess;]  - like editl except does not rebind or initialize the editor’s various 
state variables, such as lastail, unfind, undolst, marklst, etc. Should 
only be called when already under a call to еди. 


editde[pat;x;-] is the pattern match routine. Its value is T, if pat matches x. See | 
page 9.14-16 for definition of "match". 


Note: before each search operation in the editor begins, the entire pattern is scanned for atoms or 
strings containing <esc>s. These аге replaced Бу patterns of the form 
(CONS (QUOTE $) (UNPACK atom/string)) | Гог | ба, апа 
(CONS (QUOTE $$) (CONS (NCHARS atom/string) (UNPACK atom/string))), for 66.121 Thus 
from the standpoint of edit4e, pattern type ба is indicated by car[pat] being the atom $ ($ is 
€ esc >) and pattern type 6b by car[pat] being the atom $$ (< esc > < esc с >). 


Therefore, if the user wishes to call еф Че directly, he must first convert any patterns which contain 
atoms or strings ending іп <esc>s to the form recognized by edit4e. This is done with the · 


function editfpat. 


editfpat[pat;-] 2 makes a copy of pat with all patterns of type 6 converted to the 
form expected by edit4e. 


editfindp[x;pat; 12] allows a program to use the edit find command as a pure predicate | 
| from outside the editor. x is an expression, pat a pattern. The 
value of editfindp is T if the command F pat would succeed, NIL 
otherwise. cditfindp calls editfpat to convert pat to the form 
expected by edit4e, unless flg— T. Thus, if the program is applying | 
editfindp to several different expressions using the same pattern, it 
will be more efficient to call editfpat once, and then call editfindp 
with the converted pattern and flg- T. 


esubst[old;new;expr;errorflg;charflg] 
equivalent to performing (R y 9m with z as the current expression, 
ie. the order of arguments is the same as for subst. Note that y 
and/or х can employ <esc >s. The value of esubst is the modified 
г. Generates an error if y not found іп z. If errorflg— T, also 
prints an error message of the form y ?. 


esubst is always undoable. 


11 ү latter case, atom/string corresponds to the atom or string up to but not including the final two- < esc» s. In both | 
cases, dunpack is used wherever possible. 
122 


unless charflg=T and по < esc? s are specificd in new or old, in which case it is equivalent to (RC y х). Ѕее раре 
9.39. In other words, if charflg — T, and no < esc > s appear, esubst will supply them. 
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changename[fn; from;to] | 
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ИЕ str; ask flg; ше т і5 Ше пате of a function. Value is name of file т 15 contained А 
| in, ог NIL. 


editloadfns? performs wheris[fn; FNS; ;files] to obtain the пате of the 
file(s) containing fn, if апу.123 It then checks the FILEDATES 
property for each file to see if the version that was originally loaded 
still exists.24 If the file that was originally loaded no longer exists, 
but there is a different version of the file on that directory, 
editloadfns? prints "****can't find" followed by the file name, 
and then uses the version that it could find. Similarly, if the 


Original version is found, but a newer version is also found, 


editloadfns? prints "****Note: <filename> is not the 
newest version" and then uses the newest version. 


Having decided which file the function is on, if askflg=NIL, 
editloadfns? prints the value of str followed by the name of the file, 
and returns the name of the file. If askflg=T, editloadfns? calls 


 askuser giving list[fn;str;filename] as mess, the message to be 


printed. If askuser returns Y, editloadfns? returns the filename. If 
Str - NIL, "loading from" is used. | 


editloadfns? is used by the editor, loadfns (when file name is not 
Min by prettyprint, and by dwim dwim. | 


replaces all occurrences of from by to in the definition of fn. Ша. 


is an expr, changename performs nlsetq[esubst[to;from;getd[fn]]. If | 
fn is compiled, changename searches the literals of fn (and all of its 


compiler r generated аи replacing each occurrence of from 
with to. 


The value of changename is fn if at least one instance of from was 
found, otherwise NIL. 


" сћапрепате is used by break and advise for changing calls to 1 to calls to fnl-IN-fn2. 


editracefn[com] | 


123 


124 


+ + + + 


125 


instead. 


is available to help the user debug complex edit macros, or 


subroutine calls to the editor. If editracefn is set to T, the function 
editracefn is called whenever a command that was not typed in by 
the user is about to be ехесшед, giving it that command as its 
argument. However, the TRACE and BREAK options described 
below are probably sufficient for most applications. 


If there is more than one file, editloadfns? asks the user to indicate which file. 
In the case that files=T and the whereis package (Section 24) has been loaded, files(s) may be found that have not 
. been loaded or otherwise noticed, and thus will not have FILEDATES property. In this case, editloadfns? does not 


do any version checks, but simply uses the latest version. 


Will succeed even if from is called from fn via a linked call. In this case, the call will also be relinked to сай (0 
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If editracefn is set to TRACE, the name of the command and the 

current expression are printed. If editracefn=BREAK, the same 
information is printed, and the editor goes int goes into a break. The user 
can then examine the state of the editor. 


editracefn is initially NIL. 
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SECTION 10 
ATOM, STRING, ARRAY, AND STORAGE MANIPULATION - 


10.1 PNAMES AND ATOM MANIPULATION 


The term "print name" (of an atom) in LISP 1.5 referred to the characters that were output 


whenever the atom was printed. Since these characters were stored on the atoms property list 
under the property PNAME, pname was used interchangeably with "print name". In Interlisp, all 
pointers have pnames, al though only literal atoms and strings have their pname explicitly stored. 


ргілі, 


e.g., the pname of the atom ABC (D? сс consists of the five characters ABC(D. The pn ame e of the list 
(A B C) consists of the seven characters (A B C) (two of the characters are spaces). | 


Sometimes we will have occasion to refer to the rin2-pn 
The prin2-pname are those РОТЕ: output when the corresponding pointer is printed using СРЕ 


Thus (һе prin2-pname of ће atom АВС (0 is the six characters АВС%(0.3 


except that for the purposes of the functions described іп this chapter, i.e., unpack, nchars, etc. the prinl-pname of 
an integer is defined as though radix=10. Note that integers will still be printed by prin] using the current radix, as 
described in Section 14. However, we want pack[unpack[X9]] to always be X9 (and not sometimes X11) regardless 
of the setting of the radix. The user can force the prinl-pname of an integer to use current radix by setting the 


variable prxflg to T (initially NIL), e.g. with radix 8 and prxflg - NIL, nchars[9] = 1, but with prxflg=T, nchars[9] 2, 


(since 9 would now be printed by prinl as 11) Note that with radix[8] and either setting of prx flg, nchars[9 T], 
meaning use prin2-pname, would return 3, since на would print as 110. 


% is the escape character. See Sections 2 and 14. 


Note that the prin2-pname also depends on what readtable is being used (sce Section 14), since this determines 
where 25 will be inserted. Note also that the prin2-pname of an integer depends on the setting of radix. 


10.1 


The рпат е of a pointer are those characters that are output when the pointer is printed using 


++ ++ 


++ 


pack[x] 
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If x is a list of atoms, the value of pack is a single atom whose 
pname is the concatenation of the pnames of the atoms in x, e.g., 
pack[(A BC DEF G)]-ABCDEFG. If Ше pname of the value of 

pack[x] is the same as that of a number, pack[x] will be that | 
number, e.g, раскГ (1 3.4) ]=13.4, раскГ(1 E -2)]=.01. _ 


Although x is usually a list of atoms, it can be a list of arbitrary 
Interlisp pointers. The value of pack is still a single atom whose 
pname is the same as the concatenation of the pnames of all the 
pointers in x, €g., mE 

pack[ ( (A B)"CD")] - %(A% | вх) СО. | 


In other words, тарсјк ;prinl] and prinl[pack[x]] ‘ways produce the 
same output.’ In fact, pack actually operates by calling prinl to - 


convert the pointers to a stream of characters (without printing) and | 


then makes an atom out of the result. If x is not a ist с or NIL, 
pack generates an error, ILLEGAL ARG. | 


| Note: In Interlisp-I 0, atoms are restricted to < 127 дей. Attempting to ‘create a larger 


atom either via pack or by typing one in (or reading PM a fi te) will cause an error, ATOM TOO 


LONG. 


pack*[x] | 


unpack[x;flg;rdtbi] 


lambda, nospread version of pack, eg. (PACK*'« DIR'») is 
equivalent to А (LIST "е М. dia па the conses, — 


- The value of unpack is the pn ате of хаа 1 list of characters З | 


(atoms)? e.g., 
unpack[ABC] = (A B с) 
unpack["ABC(D"] = (A B C %( D) 
In other words. ріпЦх] апа ‘mapefunpack{x};prin]] produce the 
same output. 


If Пр=Т, the ore ame of x is — —— with | 
respect to ІЫ) eg, unpack["ABC(D";T]s 
(4" ABC %( 0 id | m 


Note: unpack[ x] performs n conses, where n is the number of characters in the pname of X 


| 4 Except for integers when radix is other than 10, e.g, mapc[ (X 9) ;PRIN1] produces X11 when radix is 8, but | 


pack[(X 110)]=Х9. (See footnote 1) Also, mapc[(0 5 1);PRIN1] and PRIN1[pack{(0 5 1) produce different 
results because раск (0 5 1)| is 51. | 


5 There аге no special “character- atoms" in Interlisp, i.e., an atom consisting of a single character is the same as any 


other atom. 
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dunpack[x;scratchlist;flg;rdtbl] a destructive version of unpack that does not perform any conses 


nchars[x ; flg;rdtbl] 


nthchar[x;n;flg;rdtb]] 


packc[x] 


chcon[x; flg;rdtbi] 


chconl[x] 


dchcon[x ;scratchlist; Пр га ЪЦ 


character[n] 


fcharacter[n] 


gensym[char] 


but instead uses scratchlist to make а list equal to unpack[x;flg]. If 
the p-name is too long to fit in scratchlist, dunpack calls unpack 
and returns unpack[x;flg]. Gives an error if scratchlist is not a list. 


number of characters in pname of x. 6 If fle- T, the prin2-pnam e is 
used. Eg. nchars[ "ABC" ]=3 , nchars[ "ABC"; T]-5. 


Value is nth character of pname of x. Equivalent to 
car[nth[unpack[x;flg];n]] but faster and does no conses. n can be 
negative, in which case counts from end of рпате, e.g., -1 refers to 
the last character, -2 next to last, etc. If n is greater than the 


number of characters in the pname, or less than minus that 


number, or 0, the value of nthchar is NIL. 


like pack except x is a list of character codes, ер, 3 


раскс[(70 79 79)1-Ғ00. 


like unpack, except returns the pname of x as а list of character 
codes, e.g, сһсоп[ РОО] = (70 79 79). If flg=T, the prin2- 
pname is used. | | 


returns character code of first character of pname of x, | eg, 
chconl[FOO] = 70. Thus chcon[x] could be written as - 


mapcar[unpack|[x];chcon]]. 


similar to dunpack 


n is a character code. Value is the atom having the corresponding | 


single character as its pname,® e.g. character[70] = Е. Thus, 
unpack[x] could be written as mapcar[chcon[x];character]. 


fast version of character that compiles open. 


Generates a new atom of the form xnnnn, where х-сһаг (or A if 


Both nthchar and nchars work much faster on objects that actually have an internal representation of their pname, 


i.e., literal atoms and strings, than they do on numbers and lists, as they do not have to simulate printing. 


Interlisp-10 uses ASCII code, 


See footnote 2. 
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. char is NIL) in which each of the тп is a digit. Thus, the first one 
| | . generated is A0001, the second A0002, etc. gensym provides а 
| | | mE way of generating new atoms for various uses within the system. | 
| | The value of gennum, initially 10000, determines the next 

с gensym, e.g., if gennum is set to 10023, gensym[] 2 A0024. | 


The term gensym is used to indicate an atom that was produced by the function gensym. Atoms 
generated by gensym are the same as any other literal atoms: they have property lists, and can be 
.. given function definitions. Note that the atoms are not guaranteed to be new. | 


For example, if the user has previously created A0012, either by typing it in, or via p ack or 
с gensym itself, when gennum gets to 10011, ше next value returned бу gensym иш бе Ше А00 12 
already in existence. 


mapatoms[fn] | .. Applies fn to every literal atom іп the | system, ер. а. 
| | | mapatoms| ( LAMBDA ( X) ( AND ( SUBRP X) (PRINT X)))] will 
print every subr. Value of mapatoms is NIL. 


— I-case[x;flg] _ id value is lower case version of x. If flg is Т, the first letter в. 
capitalized, e.g., l-case[F00; T] = Foo, l-case[FOO] = foo. Ifx 
is a string, the value of 1-саѕе is also a string, e.g., l-case[ "FI LE 


“. 22 | NOT FOUND";T] = "File not found". If x is a list, result is 
ж | — a new list in which lcase is computed for each corresponding 
Ж» Е ы Ж; element and non-NI L tail of the original list. 
u-case[x] Similar to 1-саѕе 
+ и-сазер[х] | Value 5 T, if x contains no lower case letters, eg. u- 
+ | | | casep[$FOO]=T, u-casep[F UN NIL. и-саѕер is handcoded and 
+ уегу efficient. ч 


10.2 STRING FUNCTIONS 


stringp[x] б Is x if x a string, NIL otherwise. Note: if x is а string, nlistp[x] is 
T, but atom[x] is NIL. | 


strequal[x;y] . Is x if x and y are both strings and equal, ie., print the same, 
| | | И | . Otherwise NIL. Equal uses strequal. Note that strings may Бе 
| MIETEN equal without being са. | 


mkstring[x] ur . Value is string corresponding to prinl-pname of x. 


rstring[-;-] | | Reads a string - see Section 14. 


10.4 


substring[x;n;m;oldptr] 


впс[х] 


gic[x] 


concat[xy ;X9}...3Xp] 


rplstring[x;n;y] 


mkatom[x] 
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Value is the substring of x consisting of the nth through mth 
characters of x. If m is NIL, the substring is the nth character of 
x thru the end of x. n and m can be negative numbers, as with 
nthchar. Returns NIL if the substring is not well defined, e.g., n or 
m > nchars[x] ог < minus[nchars[x]] or n corresponds to a 
character in x to the right of the character indicated by т. 


If x is not a string, equivalent to substring[mkstring[x];n;m], except | 


substring does not have to actually make the string if x is a literal 
atom.^ For example, substring[ (A В С);4;61-"В С". If oldptr 
is a string pointer, it is reused, otherwise substring makes. a new 
string pointer. 


get next character of string x. Returns the next character of the 
string, (as an atom), and removes the character from the string. 
Returns NIL if x is the null string. If x isn't a string, a string is 
made. Used for sequential access to characters of a string. | 


Note that if x is a substring of y, gnc[x] does not remove the 
character from y, ie. gnc doesn't physically change the string of 
characters, just the pointer and the byte count. 


gets last character, of string Х. Above remarks about gnc also 
supply to gic. е 


lambda nospread function. Concatenates (copies од any number of 

strings. The arguments are transformed to strings if they aren’t 
strings. Value iS the new string, e.g., 
concat[ "АВС"; DEF;"GHI"] = "ABCDEFGHI". The value of 
concat[] is the null string, "". 


Replace characters of string x beginning at character n with string | 


y. n may be positive or negative. x and y are converted to strings 
if they aren't already. Characters are smashed into (converted) x X. 

Returns new x. Error if there is not enough room in x for y, ie. 

the new string would be longer than the original." Note that if x is 
a substring of z, z will also be modified by the action of rpistring. 


Creates an atom whose pname is the same as that of the string x or 


бее string storage section that follows. 
See string storage section that follows. 


If y was not a string, x will iiai have been partially modified since rplstring docs not know whether y will "fit" 


without actually attempting the transfer. 


10.5 
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"+ subatom[x;n;m] 
NE 


SEARCHING STRINGS 


Section 10: Atom, String, Array, and Storage Manipulation 


if x isn’t a string, the same as that of mkstringlx], ер. 


mkatom[(A B C)] is the atom %(A% B% С%). In Interlisp-10, if 


the atom would have > 126 characters, causes an error, ATOM TOO 
LONG. 


equivalent to mkatom{substring[x: n;m]|, but does not make a string 


pointer. 


strpos is a function for searching one string looking for another. Roughly it corresponds to 


member, except that it returns a character position number instead of a tail. This number can Шеп. 


be given to substring or utilized in other calls to strpos. 


иро{раг, string ;start;skip; anchor; tail] 


EXAMPLE PROBLEM 


pat and string are agen _ Strings (or else they are converted 
ОУ Searches string beginning at character number start, 


(or else 1 if start is NIL) and looks for a sequence of characters | 
equal to pat. Jfa match is found, the corresponding character 


position is returned, otherwise NIL, e.g., 


зироз "АВС", "XYZABCDEF" ]=4 


strpos[ "АВС", "XYZABCDEF"; 5 ]=NIL 
strpos[ "АВС", "XYZABCDEFABC" ; 5 10 


skip can be used to specify a бари іп T" iit matches any 


character in string, e.g., 


strpos[ " A&C&" ; "XYZABCDEF " ; NIL; &]=4 


If anchor is Т, strpos compares pat with the characters beginning | 
at position start, or 1. If that comparison fails, strpos returns NIL | 


without searching any further down string. Thus it can be used to 


compare one string with some portion of another string, e. 8. 


strpos[ "АВС"; "XYZABCDEF " ; NIL;NIL; 1] =NIL 
strpos[ "АВС"; "XYZABCDEF";4;NIL;1]=4 


Finally, if tail is T, the value returned by strpos if successful is not 
the starting position of the sequence of characters corresponding to 
at, but the position of the first character after that, i.e., starting 


^ point plus nchars|pat]. / | |o egs 
strpos[ "ABC" ; "XYZABCDEFABC" ; NIL;NIL;NIL;T]-7. Мое 
that strpos["A" ; "А" ; NIL;NIL;NIL;T]s2, even though "A" 
has only one character. | 


Given the strings x, y, and z, write a function foo that will make a string раш to that 


portion of 


between y and _ ер, 


foo["NOW IS THE TIME FOR ALL GOOD MEN"; "15"; RE is" THE TIME Ы? 


| Solution: 
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(FOO 
[LAMBDA (X Y 7) 
(AND (SETQ Y (STRPOS Y X NIL NIL NIL T)) 
(SETQ Z (STRPOS Z X Y)) 
(SUBSTRING Х Y (SUB1 71) 


strposl[a;str;start;neg] str is a string (or else it is converted automatically to a string), a is 
a list of characters or character codes. strpos| searches str 
beginning at character number start (or else 1 if start = NIL) for one 
of the characters in а: If one is found, strposl returns as its value 
the corresponding character position, otherwise NIL. Ер, 
strposI[(A В C);"XYZBCD" 1-4. If neg=T, strposl searches for a 
character ` not on a, ер. 
strposI[(A B C); "ABCDEF";NIL;T]=4. 


If a is ап array, it is treated as а bit table (see discussion of 
makebittable below) 


If a is not a bit table (array), strpos! first converts it to a bit table using makebittable described 
below. If strposl is to be called frequently with the same list of characters, a considerable savings | 
can be achieved by converting the list to а bit table once, and then passing the bit table to strposl 
as its first argument. 


makebittable[1;neg;a] makes а bit table suitable for use by strposl. 1 is a list of characters - 
| or character codes, neg is the same as described for strposl. If a is 
not a suitable array, makebittable will create an array апа return 

that as its value. Otherwise it uses (and changes) a. 


Note: if neg=T, strposl must call makebittable whether a is a list or an array. To obtain bit table 
efficiency with neg=T, makebittable should be called with neg=T, to construct the "inverted" 
table, and the resulting table (array) should be given to strpos! with neg=NIL. | 


STRING STORAGE 


А string is stored in 2 parts; the characters of the string, and a pointer to the characters. The 
pointer, or "string pointer", indicates the byte at which the string begins and the length of the 
string. It occupies one word of storage. In Interlisp-10, the characters of the string are stored five 
characters to a word in a portion of the address space devoted exclusively to storing characters. 


Since the internal pname of literal atoms also consists of a pointer to the beginning of a string of- 
characters and a byte count, conversion between literal atoms and strings does not require any 
additional storage for the characters of the pname, although one cell is required for the string 


12 If any element of a is a number, it is assumed to be a character code. Otherwise, it is converted to a character code 


via chconl. Therefore, it is more efficient to call strposl wan а a list of character codes. 
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pointer. 1 


When the conversion is done internally, е.р., as in substring, strpos, or strposl, no additional ове 
ds required for using literal atoms instead of strings. 


The use of storage by the basic string functions is given below: 


mkstring[x] | x string | по space 
. Xx literal atom . new pointer mE 
other new characters and pointer 
substring[x;n;m] x string E new pointer 
| x literal atom new pointer | 
other 5 new characters and pointer 
gnc[x] апа ех] х string | | по space, pointer is modified 
other y ^ like mkstring, but doesn't make much sense 
сопса{хт;хә;..ху] - args any type | new characters for whole new string, one new 
5-54 | pointer 
. rpistring[x;n;y] Xx String | | no new space unless characters are in pname - 


space (as result of mkstring[atom]) in which case 
| x is quietly copied to string pae 
x other new pointer and characters | | 
у апу type . type of у doesn't matter 


10.3 ARRAY FUNCTIONS 


Space for arrays and compiled code are both allocated out of a common array space. Arrays of 
pointers and unboxed numbers may be manipulated by the following functions: 


array[n;p;v] This function allocates a block of n--2 words, of which the first two 
| are header information. Іп Interlisp-10, the next p < n are cells 
which will contain unboxed numbers, and are initialized to unboxed 
0. The last п-р > 0 cells will contain pointers initialized with v, 
i.e., both car and саг are available for storing information, and each 
initially contain v. ЛЕ p is NIL, 0 is used (1е., an array containing 
all Interlisp pointers). The value of array is the array, also called an 
array pointer. If sufficient space is not available for the array, a 
garbage collection of array space is initiated. If this is unsuccessful 
in obtaining sufficient space, an error is generated, ARRAYS FULL. 


13 Except when the string is to be smashed by rplstrin ng. In this case, its characters must be copied to avoid smashing | 
_ the pname of the atom. rplstring шры performs this operation, | 
14 


except when substring is given a string pointer to reuse as its fourth argument. Note that Ви -1] copies 
just the string pointer without copying the characters, 
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Array Functions 


Array-pointers print as An, where n is the oelai representation of the DOM Note that #n will 
be read as a literal atom, and not an array pointer. 


arraysize[a] 


arraytyp[a] 


arrayp[x] 


атгауђерјај 


harray[n] 


harraysize[a] 


harrayp[x] 


swparraypl[x] 


elt[a;n] 


seta[a;n;v] 


I»: 


16 


Value is the size of array a. Generates an error, ARG NOT 
ARRAY , if a is not an array. | 


Returns a value corresponding to second argument to array. In 
Interlisp-10, this is the number of unboxed аттау words of array a. 


Value is x if x is an array pointer otherwise NIL. No check is 


made to ensure that x actually addresses the beginning of an array. 


if a is a pointer into the middle of an array, returns the pointer to 
its beginning. Otherwise returns NIL. 


Creates hash array of size n (see Section 7). 


Value is the size of hash array а. 


Value is x if x is a hash array (see Section 7). 
Value is x if x is a swappable array, NIL otherwise. 


Value is nth element of the array a? elt generates an error, ARG 


NOT ARRAY, if a is not the beginning of an аггау.16 If n 


corresponds to the unboxed region of a, the value of elt is the full 
36 bit word, as a boxed integer. If n corresponds to the pointer 
region of a, the value of elt is the car half of the corresponding 
element. 


sets the nth element of the array а. Generates an error, ARG NOT | 


ARRAY, if а is not the beginning of an array. If n corresponds 10 


the unboxed region of a, v must be a number, and is unboxed and | 


stored as a full 36 bit word into the nth element of a. If n 
corresponds to the pointer region of a, v replaces the car half of the 


nth element. The value of seta is v. 


elt[a;1] is the first element of the array (actually corresponds to the 3rd cell because of the 2 word header). 


arrayp is truc for pointers into the middle of arrays, but elt and seta must be given a pointer to the beginning of an 
array, i.e., a value of array. | 
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Note that seta and elt are always inverse operations. 


eltd[a;n] 


setd[a;n;v] 


same as clt for unboxed region of a, but returns cdr half of nth 
element, if n corresponds to the pointer region of a. 


same as seta for unboxed region of a, but sets cdr half of nth 
element, if n n corresponds to the pointer region of a. The value ЖУ; 
setd is v. 


In other words, eltd and setd are always inverse operations. 


Creates a new array of same size and type as ar, ie. same 
distribution of pointers and unboxed numbers, and with the same 
contents. as аг | Value is пем array. Generates ап 
ARG NOT ARRAY error, if ar is not an array. | 


10.4 STORAGE FUNCTIONS 


_ + copyarray[ar] 
= | | 
+ 
+. 
* 
* 
.* {уре number 
* 1 
z 2 
i: 4 
е. 5 
* 6 
j 7 
* : 8 
* 9 
x 12 
ы 16 
Ы 18 
* 20 
T 24 
i 28 
T 30 
-+ typename[datum] 
E s 
+ 
+ 
4 17 
+ 


The table below contains the built in Interlisp data types and their corresponding type number and 
type name. User data types are assigned pen numbers beginning with 31. “5 С 


type пате 2222 description 
АВВАҮР arrays, compiled code 
STACK X .machine code 
SWPARRAYP . |. - swapped array handles 
STACKP stack pointers 
GC.BTAB bit tables 
ATOM.HASH | atom hash table 17 
LISTP . A list words 
VCELLP value cells 
ATOM . atoms 
FLOATP floating point numbers - 
FIXP large integers 
SMALLP  . . small integers 
STRINGP string pointers 
ATOM.CHARS pname storage 


STRING.CHARS  — string storage 


Value is type name for the data type of datum. For user data types 
(Section 3), the type name is spccified by Ше call to 


declaredatatype. For built in data types, typename is one of the 
atoms, LISTP, FLOATP, ҒІХР, STRINGP, | ТТАТОМ, 


The atom hash table automatically expands by a specified number of pages each time it fills up. The number of 
pages is set via the function minhash. The initial setting is minhash[2] (room Гог 1024 new atoms). 
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| typenamep[datum;typename] 


typenamefromnumber[n] 


typenumberfromname[name] 


ntyp[datum] 


typep[datum;n] 


reclaim[type] 


Storage Functions 


STACKP, АВВАУР,В SWPARRAYP, SMALLP. | 


True if the typename of datum is equal to typename. Compiles | 
open, 


value is type name for type number п, or NIL if n is not a valid 
type number, e.g. typenamefromnumber[30]=STRING. CHARS. | 


value is corresponding type number for name, or NIL if name is 
по а type 0 пате, “ eg. 
typenumberfromname[STRING . CHARS]= 30 19 


Value is type number for the data type of datum, eg. 
ntypL(A . B)] is 8, the type number for lists. 


_ value is T, if the type number of datum is equal to n. 


Initiates a garbage collection of type type, where type is either a 
type name or type number. Value of reclaim is number of words 
available (for that type) after the collection. 


Garbage collections, whether invoked directly by the user or indirectly by need for storage, do not 
confine their activity solely to the data type for which they were called, but automatically collect 
some or all of the other types (see Section 3). 


gcgag[message] 


18 


affects messages printed by garbage collector. If message=T, 
whenever a garbage collection is begun, "collecting" is printed, 
followed Бу {һе type description of the type that initiated the 
collection. When the garbage collection is complete, two numbers 
are printed: the number of words collected for that type, and the 
total number of words available for that type, i.e., allocated but not 
necessarily currently in use. Note that other types may also have 


been collected, and had more storage assigned, as explained in 


Section 3. 


typename distinguishes the five logical data types, READTABLEP, TERMTABLEP, CCODEP, ARRAYP and 


POINTER. INTO. ARRAY . SPACE, though they ай have the same type number and share the same data space. 


19 


typenumberfromname will accept READTABLEP, TERMTABLEP, CCODEP, and ARRAYP, and return the same value 


Гог each, which for Interlisp-10 is 1. Note however that typenamefromnumber[{]]=ARRAYP, 


20 


Note that this type description can be өсі via the function scttypedescription described below. 
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gcmess[message # ;string] 
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Example: 
+RECLAIM( 18) 


collecting large numbers | 
511, 3071 free cells 

3071 | 
«БЕСІ АІМ(1.1ТАТОМ) 


collecting atoms 
1020, 1020 free се115' 
1020 | 


If message =NIL, no garbage collection message is printed. either | 
оп entering or leaving the garbage collector. | | 


If message is а list, car ОҒ message is printed (using prin nl) when the . 
garbage collection is begun, and cdr is printed (using prinl) when 
the collection is finished. If message is a literal atom or string, 
message is printed when the garbage collection is begun, and 
nothing is printed when the collection finishes. 


If message is a number, the message is the same as for gcgag[T], - 
except if the total number of free pages left after the collection is 
less than message, the number of free pages is printed, e.g., 
-GCGAG( 100) | 
T . | 

_ *RECLAIM() 


collecting lists 
10369, 10369 free cells, 87 pages left. 


The initial setting for gcgag is 40. 


The value of рсрар 15 its previous setting. 


gcgag is implemented in terms of the primitive gcmess which can - 
be used to further refine garbage collection messages for specialized 
applications. The garbage collection message is actually composed 
ОҒ seven separate messages: 


collecting large numbers 
3 4 5 6 E 
511, 3071 free cells, 87 pages left 


-message #1 is the "collecting" string. If NIL, then neither it, nor 
the type dependent field (which is settable via settypedescription 
described below) is printed. 
теѕѕаре #2 is the carriage-return after the type-dependent field. 
Thus to simply print a string at е beginning of a garbage 
collection, perform gcmess[1] and gcmcess[2;string]. 
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срива вена т ы 


gettypedescription[type] 


settypedescription[type;string] 


minfs[n;type] 


Storage Functions 


"о" 


message #3 is the "," which comes after the number of cells 


actually collected. If NIL, then neither it nor that number are 


printed. 


message # 4 is the "free cells" which comes after the number. of 


cells that are now allocated. If NIL, neither it nor that number are 
printed. | | 


message#5 is the number of pages left below which the system | 


prints message # 6, 


message #6 is the "pages left" message. If NIL, neither it nor the 
number of pages left are printed. | 


message #7 is the terminating carriage return. 


returns the type description string for t type, a type name or type 


number. 


sets the type description string for type to be string. The type 


description is used in garbage collection messages and by s Storage 
(described Pen | 


Sets the minimum amount of free storage which will be maintained К 
by the garbage collector for data types of type number or type | 


name type. If, after any garbage collection for that type, fewer than 


Fer pk eN 


++ 


dui 


n free words аге present, sufficient storage will be added (in 512. Е 


word chunks) to raise the level to n. 
If typ-NIL ; 115ТР $$ used, j.e., | the minfs refers to list words. 


If n=NIL, minfs returns the current minfs к Гог the 
corresponding type. 


A minfs setting can also be changed dynamically, even during a garbage collection, by typing 
control-S2! followed by a number, followed by a period.” If the control-S was typed during a 
garbage collection, the number is the new minfs setting for the type being collected, otherwise for 


type 8, i.e., list words, 


Note: A garbage collection of a "related" type may also cause more storage to be assigned to that 


type. See discussion of garbage « collector MURORUM Seclion 3. 


21 


22 


control-X for Interlisp-10 on TOPS-20. 


When the control-S is typed, Interlisp immediately clears and saves the input buffer, rings the bell, and waits for 


input, which is terminated by any non-number. The input buffer is then restored, and the program continues. If the 
input was terminated by other than a period, it is ignored. | | 
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storageľfig: gcflg] Prints amount of storage used by and assigned to the user, e.g., 
-STORAGE( ) | | | 
TYPE . | USED ASSIGNED 
ARRAYP | arrays 12754 12800 
STACK | 22 stack, swap buffer 14336 _ 14336 
SWPARRAY swap array handles 29 512 
STACKP | stack pointers 0 512 
GC .BTAB gc као IS 2048 2048 
LISTP lists 5016 11776 
VCELLP |J value cells 194 1024 
LITATOM atoms 2028 3072 | 
FLOATP float numbers 1 512 
FIXP . . large numbers 70 2048 
STRINGP string pointers 173 512 
ATOM.CHARS atoms have characters 1594. 2048 
STRING.CHARS string characters 421 1024 
. SUM (137 pages left) 38664 52224 
c Note that the storage used by a particular type is only accurate 
+ immediately following a garbage collection of а related type. If 
T рсе = T, storage will perform the necessary garbage collections 
t before printing its results. If flg— T, includes storage used by and 
+ assigned to the system. Value is NIL. 
+ gctrp[n] garbage collection trap. Causes a (simulated) control-H interrupt 
+ | | when the number of free list words remaining equals п, 1е., when а 
+ garbage collection would occur in n more conses. The message 
+ GCTRP is printed, the function interrupt (Section 16) is called, and 
+ a break occurs. Note that by advising (Section 19) i interrupt the 
+ user can program the Рв of a рсир instead of going into a 
+ break. 
+ Value of gctrp is its last setting. 
+ gctrp[-1] 27 will "disable" a previous gctrp since there are never -1 free list 
T | words. gctrp is initialized this way. 
T gctrp[] returns number of list words left, i.e., number of conses until 
+ next type LISTP garbage collection, see Section 21. 
+ conscount[n] | conscount[] returns number of conses since Interlisp started up. If 
ПВО взе с n is not NIL, resets conscount to n. 


23 Бог gctrp interrupts, interrupt is called with intype (its third argument) equal to 3. If Ше user does not want to go 
into a break, the advice should still allow interrupt to be entered, but first set intype to -1. This will cause interrupt 
to "аше у" go away by calling the function that was interrupted. The advice should not exit interrupt via return, as 


оо in this case the function that was about to be called when the interrupt occurred would not be called. 
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closer[a;x] Stores x into memory location a. Both x and a must be numbers. + 


орепца| Value is Ше number in memory location а, 1.е., boxed. + 
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SECTION 11 | 
FUNCTIONS WITH FUNCTIONAL ARGUMENTS - 


As in all LISP 1.5 systems, arguments can be passed which can then be used as functions. 
However, since car of a form is never evaluated, apply or apply* must be used to call the function 
specified by the value of the functional argument. 


Functions which use functional arguments should use variables with obscure names to avoid 
possible conflict with variables that are used by the functional argument. For example, all system 
functions standardly use variable names consisting of the function name concatenated with x or fn, 
e.g., тарх. Note that by specifying the free variables used in a functional argument as the second | 
argument to function, thereby using the Interlisp F UNARG feature, the user can De sure of no 
clash. HR. 


function[fn;env] is an nlambda function. If env=NIL, the Vds of function is 
identical to quote, for example, 
(MAPC LST (FUNCTION PRINT)) will cause mapc to be called. 
with two arguments, the value of Ist and PRINT. Similarly, | 
[MAPCAR LST (FUNCTION (LAMBDA(Z) (LIST (CAR 7] 
will cause mapcar to be called with the value of Ist and 
(LAMBDA (Z) (LIST (CAR Z))). When compiled, function 
will cause code to be compiled for fn; quote will not. Thus | | 
(MAPCAR LST (QUOTE (LAMBDA --))) will cause 
mapcar to be called with the value of Ist and the expression 
(LAMBDA --). The functional argument will therefore still Бе 
interpreted. The corresponding expression using function will cause 
a dummy function to be created with definition (LAMBDA --), 
and then compiled. mapcar would then be сайса with the value of | 
Ist and the name of the dummy function. See Section 18. 


If env is not NIL, it can be a list of variables that are (presumably) 
used freely by fn. In this case, the value of function is an 
expression of the form (FUNARG fn pos), where pos is a stack 
pointer to a frame that contains the variable bindings for those 
variables on env. env can also be a stack pointer itself, іп which 
сазе the value of function is (FUNARG fn env). Finally, env can 
be an atom, in which casc it is evaluated, and the value interpreted 
as described above. Funarg is described on page 11.3-5. 
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map[mapx;mapfnl;mapfn2] If mapfn2 is NIL, map applies the function mapfnl to successive 
ШЕ tails of the list тарх. That is, first it computes тар а (тархј, апа 
then mapfnl[cdr[mapx]], etc., until тарх is exhausted.! If mapfn2 is 
provided, mapfn2[mapx] is used instead of cdr[mapx] for the next 
call for mapfnl, e.g., if mapfn2 were cddr, alternate elements of the 
list would be skipped. 


The value of map is NIL. map compiles open. 


mapc[mapx;mapfnl;mapfn2] Identical to map, ‘except that шарт сай тару i 15 computed. at. 


each iteration instead of mapfnl[mapx] | шаре works on 
. elements, map on tails. The value of mapc is NI L. mapc compiles 
open. | 


maplist{mapx: mapfnl;mapfn2] successively computes the same values that map would compute, | 
and returns а list consisting of those values. maplist compiles open. 


mapcar[mapx;mapfn1; mapfn2] computes the same values that mapc would compute, and returns a 
list consisting of those values, e.g., mapcar[x;FNTYP] is a list of 
fntyps for each element on x. mapcar pup open. 


mapcon{mapx;mapfnl;mapfn2] computes the same values as map and — but nconcs these. 
values to form a list which it returns. mapcon compiles open. | 


mapconc[mapx ;mapfnl ; :mapfn2] 
Computes the same values. asm apc and mapcar, but nconcs the 
values to form a list which it returns. mapconc compiles open. 


. Note that mapcar creates а new list which is a mapping of the old list in that each element of the 
new list is the result of applying a function to the corresponding element on the original list. 

mapconc is used when there are a variable number of elements (including none) to be inserted at 
each iteration, e.g. mapconc[x;( LAMBDA (Y) (AND Y (LIST Y)))] will make a list consisting | 


of x with all NILs removed, mapcondx;(LAMBDA (Y) (AND (LISTP Y) Y))] will make a 
lincar list consisting of all the lists on x, e.g., if applied to ((A B) С (D E F) (6) Н I) wil — 


yield (A B D E F G).? 


subslfmapx ‘mapfnl;mapfn2] applies mapfnl to elements of тарх and returns а list of those 
elements for which this application is non-NIL, ер. 


i.e., becomes a non-list. 


Note that since mapconc uses nconc to string the corresponding lists together, in this example, the original list will be 
clobbered, ie. it would now be ((A B D E Е 6) C (D E Е б) (G) H I). If this is an undesirable side 
effect, the functional argument to mapconc should return instead a top level copy, e.g., in this case, use 
(AND (LISTP Y) (APPEND Ү)). 
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subset? (A В 3 C 4);NUMBERP] = (3 4). 
mapfn2 plays the same role as with map, тарс, et al. subset 
compiles open. 


map2c[mapx;mapy;mapfnl;mapfn2] 
Identical to тарс except mapfnl is a function of two arguments, 
and mapfnl[car[mapx];car[mapy]] is computed at each iteration. 
Terminates when either mapx or mapy are exhausted. 


тар2са тарх ;mapy;mapfnl;mapfn2] 
Identical to mapcar except т тари! is a function of two arpuments 
and mapfnl[{car[mapx];car[mapy]] is used to assemble the new list. 
Terminates when either mapx or mapy is exhausted. | 


Note: CLISP (Section 23) provides a more general and complete facility for expressing iterative 
statements, ер. (FOR Х IN Y COLLECT (CADR X) WHEN (NUMBERP (CAR X)) UNTIL 
(NULL X)). 


 maprint[lst;file;left;right;sep;pfn;lispxprintflg] 
is a general printing function. It cycles through Ist applying рѓа (ог | 
prinl if pfn not given) to each element of Ist. Between each 
application, maprint performs prinl of sep, ог" " if sep=NIL. If 
left is given, it is printed (using prinl) У if пан! 15 Een it is- 
printed (using prinl) at the end. | 
For example, maprint[x;NIL:%(;%)] is equivalent to prin] for lists. 
To print a list with commas between each element and a final "." 
one could use maprint[x; T ; NIL;%.;%,]. 


If lispxprintflg — T, lispxprinl is used for prinl (see Section 22). 
mapdl,searchpdl See Section 12. 
mapatoms See Section 5. 
every, some, notevery, notany See Section 5. 


FUNARG 


function is a function of two arguments, fn, a function, and env is cither NIL, a list of variables 


mapfn2 is still a function of one argument, and is applicd twice on each iteration; mapfn2[mapx] gives the new 
тарх, mapfn2[mapy] the new тару. cdr is used if mapfn2 is not supplicd, i.e, is NIL. 
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used freely by fn, a stack pointer, ог an atom. If env is a list of variables, the value of function is 


an expression of the form (FUNARG fn pos), where pos is a stack pointer to a frame that 


contains the bindings of the variables on env at the time the call to function was evaluated. If env 


is a stack pointer, the value of function is (FUNARG fn env). 


funarg is not a function itself. Like LAMBDA and NLAMBDA, it has meaning and is specially 


recognized by Interlisp only in the context of applying a function to arguments. In other words, 
the expression (FUNARG fn pos) is used exactly like a function. ? When a funarg is applied or is 
car of a form being eval'ed, the apply or eval takes place in the access environment specified by 
env (see Section 12). 


For example, suppose a program wished to compute (FOO X (FUNCTION FIE)), and fie used 
y and 7 as free variables. If foo rebound y and z, fie would obtain the rebound values when it was 
applied from inside of foo. By evaluating instead (FOO X (FUNCTION FIE (Y Z))), foo 
would be called with (FUNARG FIE pos) as its second argument, where pos contained the 
bindings of y and z (at the time foo was called). Thus when fie was applied from inside of foo, it 
would "see" the original values of y and z. 


However, funarg is more than just a way of circumventing the clashing of variables. For example, 
a funarg expression can be returned as the value of a computation, and then used "higher up". 
Furthermore, if the function in a funarg expression sets any of the variables contained in the 
frame, only the frame would be changed. For example, suppose foo is defined as 
(LAMBDA (LST FN) (PROG (Y Z) (SETQ Y &) (SETQ 2 8) 

(MAPC LIST FN) | 


апа (FOO Х (Е UNCTION FIE (Y Z))) is evaluated. If one application of fie (by the mapc in 


foo) changes у and 7, then the next application of fie will obtain the changed values of у and 7 
resulting from the previous application of fie, since both applications of fie come from the exact _ 
same funarg object, and hence use the exact same frame. The bindings of y and z bound inside of 


foo, and the bindings of y and z above foo would not be affected. In other words, the variable | 


bindings contained in pos are a part of the he function object, i.e., the funarg carries its environment 
with it. 


"Thus by creating а funarg expression with function, a program can create a function object which - 


has updateable binding(s) associated with the object which last between calls to it, but are only 
accessible through that instance of the function. For example, using the funarg device, a program | 


could maintain two different instances of the same random number generator in different states, 


and run them independently. 


EXAMPLE 


If foo is defined as (LAMBDA (X) (COND ((ZEROP А) X) (T (MINUS X)))) and fie as 
(LAMBDA NIL (PROG (A) (SETQ A 2) (RETURN (FUNCTION ЕОО)))). then if we 
perform (SETQ A 0), (SETQ FUM (FIE)), the value of fum is FOO, and the value of 
(APPLY* FUM 3) is 3, because the value of A at the time foo is called is 0. | 


If env is NIL, the value of function is simply fn, i.e., not a funarg expression. If env is ап atom, it is evaluated and 
its value interpreted as described above. 


5 LAMBDA, NLAMBDA, and FUNARG expressions are somctimes called “function objects" to distinguish them from 
functions, 1.с., literal atoms which have function definitions. 
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However if fie were defined ТТІ а5 ae 

(LAMBDA NIL (PROG (A) (SETQ A 2) (RETURN (FUNCTION FOO (А))))), the value of 
_ fum would be (FUNARG FOO pos) and so the value of (APPLY* РИМ 3) would be -3, because 

the value of A seen by foo is the value А had when the funarg was created inside of Пе, 1.е., 2. 
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VARIABLE BINDINGS, PUSH DOWN LIST FUNCTIONS, 
AND THE SPAGHETTI STACK 


A number of schemes have been used in different implementations of LISP for опа (һе values 
of variables. These include: 


1. Storing values on an association list paired with the variable names. 
2. Storing values on the property list of the atom which is the name of the variable. 
3. Storing values іп а special value cell associated with the atom name, putting old values 


on a pushdown list, and restoring these values when exiting from a function. 


4. біогіпр values оп a pushdown list. 


In Interlisp, we currently use the third scheme, so called "shallow binding". When a function is- 


entered, the value of each variable bound by the function (function argument) is stored іп a value 
cell associated with that variable name. Тһе value that was іп the value cell is stored in a block of 


storage called the basic frame for this function call. In addition, on exit from the function each 


variable must be individually unbound; that is, the old value saved in the basic frame must be 


restored to the value cell. Thus there is a higher cost for binding and unbinding a variable than іп 


the fourth scheme, "deep binding". However, to find the current value of any variable, it is only 
necessary to access the variable's value cell, thus making variable reference considerably cheaper 
under shallow binding than under deep binding, especially for free variables. Our measurements 
have indicated that typically more time is spent in variable reference under the deep binding 
scheme than is lost in binding and unbinding under shallow binding. However, the shallow binding 
scheme used does require an additional overhead in switching contexts when doing "spaghetti 
stack" operations; this is described in more detail on page 12.6. | T 


The basic frames are allocated on a stack or pushdown list; for most user purposes, these frames . 


should Бе thought of as containing the variable names associated with the function call, and the 


current values for that frame. The descriptions of the stack functions in Sections 12.3 and 12.4 are 


presented from this viewpoint. Doth interpreted and compiled functions store both the names and 
values of variables so that interpreted and compiled functions are compatible and can be freely 
intermixed, 1.е., free variables can be used with no special declarations necessary. The names are 


However, it is possible to suppress storing of names in compiled functions, either for efficiency or to avoid a clash, 
ма a LOCALVAR declaration (see Section 18). 
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also very useful in debugging, for they make possible a complete symbolic backtrace in case of 


error. 


In addition to the binding information, additional information is associated with each function call: 


control information indicating the calling function, access information indicating the path to search 


the basic frames, and temporary results are also stored on the stack in a block called the frame 
extension. Тһе interpreter also stores information about partially evaluated expressions а 
described below. | 


12.1 THE PUSH-DOWN LIST AND THE INTERPRETER 


In addition to the names and values of arguments for functions, information regarding partially- 


evaluated expressions is kept on the push-down list. For example, consider the following definition 
of the function fact (intentionally faulty): 


(FACT 
[LAMBDA (N) 
(COND - 
((ZEROP N) 
L) 
(Т (ITIMES N (FACT (SUB1 М1) 


In evaluating the form (FACT 1), as soon as fact is entered, the interpreter begins evaluating the 
implicit progn following the LAMBDA (see Section 4). The first function entered in this process is - 
cond. cond begins to process its list of clauses. After calling zerop and getting а NIL value, cond 
proceeds to the next clause and evaluates T. Since T is true, the evaluation of the implicit progn 


2 that is the consequent of the T clause is begun (see Section 4). This requires calling the function 
itimes. However before itimes сап be called, its arguments must be evaluated. The first argument 


is evaluated by retrieving the current binding of n from its value cell; the second involves a 
recursive call to fact, and another implicit progn, etc. | 


Note that at each stage of this process, some portion of an expression has been evaluated, and 


another is awaiting evaluation. The output below illustrates this by showing the state of the риѕћ- 
down list at the point in the computation of (FACT 1) when the unbound atom L is reached. 
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-FACT(1) 

u.b.a. L (in FACT) in ((ZEROP N) L) 
(1 BROKEN) | 

: BTV! 


*TAIL* (L) 


."ARGI (((ZEROP N) за (amnes N (FACT (5081 N))))) 


*FORM* (COND ((ZEROP N) L) (T (ITIMES N (FACT (SUB1 N)))) -— 
*TAIL* ((COND ((ZEROP N) L) (Т (ITIMES М (РАСТ (5081 М)))))) 
NO 
FACT 
*FORM* (FACT (SUB1 N)) 
*FN* ITIMES 
*TAIL* ((FACT (5081. N))) 
*ARGVAL* 1 
*FORM* (ITIMES М (FACT (5081 N))) 
*TAIL* ((ITIMES N (FACT (SUB1 N)))) 
"ARG1 (((ZEROP N) L) (T (ITIMES N (FACT (5081 N))))) 
ND ii | AN шы 
*FORM* (COND ((ZEROP М) L) (T (ITIMES N (РАСТ (SUB1 N)))))- 
*TAIL* ((COND ((ZEROP N) L) (T (ITIMES N (FACT (SUB1 N)))))) 
М1 
ҒАСТ 


«# ТОР“ # 


Internal calls to eval, e.g., from cond and the interpreter, x marked on the КҮ -down list by а 
special mark or blip which the backtrace prints as *FORM*.? The genealogy of *FORM*’s is thus a 
history of the computation. Other temporary information stored on the stack by the interpreter 
includes the tail of a partially evaluated implicit progn (с.р., а cond clause or lambda expression) 
and Ше tail of a partially evaluated form (i.e. those arguments not yet evaluated), both indicated | 
on the backtrace by *TAIL*, the values of arguments that have already been evaluated, indicated | 
Бу *ARGVAL*, and the names of functions waiting to be called, indicated by “ЕМ”... *ARG1, 
*ARGn are used by the backtrace to indicate the (unnamed) arguments to subrs. | 


Note that а function is not actually entered and does not appear on the stack, until its arguments | 
have been evaluated.) Also note that the *ARG1, *FORM*, *TAIL*, etc. "bindings" comprise - 


2 Note that *FORM*, “ТАП”, *ARGVAL*, etc., do not actually appear on the backtrace, i.e., evaluating *FORM* 
or calling stkscan to search for it will not work. However, the functions blipval, setblipval, and bli ipscan described | 
below аге available for accessing these internal blips. | 


3 except for functions which do not have thcir arguments шо (although they themselves may сай eval, e.g, 
cond). 
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the actual working storage. In other words, in the above example, if a (lower) function changed 
the value of the *ARG1 binding, the cond would continue interpreting the new binding as a list of 
cond clauses. Similarly, if the *ARGVAL* binding were changed, the new value would be given to 
itimes as its first argument after its second певати had been evaluated, апа itimes was actually 
called. | 


BLIP FUNCTIONS 


| Тһе temporaries of the interpreter, or blips, can be accessed by the following three functions, КИЕП 
ин know about four different types of blips: К 


ы ЕМ». - the name of a function about to be called 
*ARGVAL* ап argument for a function about to be called 
*FORM* a form in the process of evaluation 

*TAIL* е tail of a cond clause, implicit progn, prog, etc. 


blipval[bliptyp;ipos;flg] ^ | Returns the value of the specified blip of type bliptyp. If flg is a 
ML Un . number, finds the nth blip of the desired type, searching the 
control chain beginning at the frame specified by the stack 
descriptor ipos. If flg is NIL, l is used. If flg is T, returns the 
number of blips of the specified type агро. —— 


setblipval[bliptyp;ipos;n;val] - | D „ый У oat sa 

| marne „= © _ Sets the value of the specified Мір of type bliptyp. Searches for 

-. the nth blip of the desired type, beginning with the frame specified 
Әу the stack descriptor ipos, and following the control chain. - 


 blipscan[bliptyp;ipos] Returns a stack pointer to the frame in which a blip of type bliptyp 
| = 15 located. Search begins at the frame specified by Ше stack 
| descriptor ipos and follows the contro! chain. 


12.2 THE SPAGHETTI STACK 


The Bobrow/Wegbreit paper, "A Model and Stack Implementation for Multiple Environments" 
· [Bob3], describes an access and control mechanism more gencral than the simple pushdown stack. - 
Тһе access and control mechanism used by Interlisp is a slightly modified version of the one 
proposed by Bobrow and Wegbreit. This mechanism is called the "spaghetti stack." _ 


Тһе spaghetti system presents the access and control stack as а data structure composed of 
"frames." The functions described below operate on this structure. These primitives allow user 


functions to manipulate the stack in a machine independent way. Backtracking, coroutines, and 
morc sophisticated control schemes can Әс casily implemented with these primitives. 


|. OVERVIEW OF SPAGHETTI STACK 


The evaluation of a function requires the allocation of storage to hold the values of its local 
variables during the computation. In addition to variable эшш ап activation of а function 
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requires a return link (indicating where control is to go after the completion of the computation) 
and room for temporaries needed during the computation. In the spaghetti system, one "stack" is 
used for storing all this information, but it is best to view this stack as а tree of linked objects 
called frame extensions (or simply frames). 


A frame extension is a variable sized block of storage containing a frame name, a pointer to some 
variable bindings (the blink), апа two pointers to other frame extensions (the alink and clink). 
addition to these components, a frame extension contains other information (such as temporaries 
and reference counts) that does not interest us here. 


The block of storage holding the variable bindings is called a basic frame. A basic frame is 
essentially an array of pairs, each of which contains a variable name and its value. The reason 
frame extensions point to basic frames (rather than just having them "built in") is so that two 
frame extensions can share a common basic frame. This allows two DISSE to communicate via 
shared variable bindings. 


The chain of frame extensions which can be reached via the successive alinks from a given frame is- 
called the access chain of the frame. Тһе first frame in the access chain is the starting frame. Тһе 
chain through successive clinks is called the control chain. 


A frame extension completely specifies the variable bindings and control information necessary for 
the evaluation of a function. Whenever a function (or in fact, any form which generally binds local 
variables) is evaluated, it is associated with some frame extension. | 


In the beginning there is precisely one frame extension in existence, This is the frame in which 
the top-level call to the interpreter is being run. This frame is called the "top-level" frame. 


Since precisely one function is being executed at any instant, exactly one frame is distinguished as 
having the "control bubble" in it. This frame is called the active frame. Initially, the top-level 
frame is the active frame. If the computation in the active frame invokes another function, a new 
basic frame and frame extension are built. The frame name of this basic frame will be the name 
of the function being called. The b-, а-, and clinks of the new frame all depend on precisely how 
the function is invoked. The new function is then run in this new frame by passing control to that 
frame, 1.е., it is made the active frame. 


Once the active computation has been completed, control normally returns to the frame pointed to 
by the clink of the active frame. That is, the frame in the clink becomes the active frame. 


In most cases, the storage associated with the basic frame and frame extension just abandoncd can 
be reclaimed. However, it is possible to obtain a pointer to a frame extension and to "hold on" to 
this frame even after it has been exited. This pointer can be used later to run another computation | 
in that environment, or even "continue" the exited computation. 


A separate data type, called a stack pointer, is used for this purpose. А stack pointer is just a cell 
that literally points to a frame extension. Stack pointers print as #adr/framename, e.g., 
#117753/COND. Stack pointers are returned by many of the stack manipulating functions 
described below. Except for certain abbreviations (such as "the frame with such-and-such a 
name"), stack pointers arc the only way the user can reference a frame extension. As long as the 
user has a stack pointer which references a frame extension, that frame extension (and all those 
that can be reached from it) may not (will not) be garbage collected. 


Note that two stack pointers referencing the same frame extension are not necessarily eq, 1.с., (EQ 
(STKPOS 'FOO) (STKPOS 'FOO))=NIL. However, сар can be used to test if two different 
stack pointers reference the same frame extension, 
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It is possible to evaluate a form with respect to an access chain other than the current one by using 
a stack pointer to refer to the head of the access chain desired. When evaluating the form, since 
all references to variables under the shallow binding scheme go through the variable's value cell, 
the values in the value cells must be adjusted to reflect the values appropriate to the desired access 
chain, This is done by changing all the bindings on the current access chain (all the name-value 
pairs) so that they contain the value current at the time of the call. Then along the new access 
path, all bindings are made to contain thc previous value of the variable, and the current value is 
placed in the value cell. For that part of the access path which is shared by the old and new 
chain, no work has to be done. The context switching time, i.e. the overhead in switching from the 
current, active, access chain to another one, is directly proportional to the size of the two branches 


that are not shared between the access contexts. This cost should be remembered in using 


coroutines and generators, as described below. 


12.3 STACK FUNCTIONS 


In the descriptions of the stack functions below, when we refer to an argument as a stack 
descriptor, we mean that it is either a stack pointer or one of the following abbreviations: | 


l. NIL means the active frame; that is, the frame of the stack function itself. 
2. T means the top-level frame. 
3. Any other literal atom is equivalent to (5ТКРО5 АТОМ -1). 


4. A number is equivalent to (STKNTH number). 


In the stack functions described below, the following errors can occur. 


ILLEGAL STACK ARG /Оссшв when a stack descriptor is expected and the supplied | 
| | | argument is either not а legal stack descriptor (е. not a stack 
pointer, litatom, or number), or is a litatom or number for which 
there 15 no corresponding stack frame (е.2., (STKNTH -1 (QUOTE 
FOO)) where there is no frame named FOO in the active control 

chain or (STKNTH -10 (QUOTE EVALQT )). 


STACK POINTER | | 
HAS BEEN RELEASED | | Occurs whenever a released stack pointer is supplied as a stack 


descriptor argument for any purpose other than as a stack pointer 
to re-use. 
FUNCTIONS 


| stkpos[framename; n;ipos; opos] Scarch for the nth frame with name framename. The search begins 


with (and includes) the frame specified by the stack descriptor ipos 
. (initial position). The search proceeds along the control chain from 
 ipos if n is negative, or along the access chain if n is positive. If n 
is NIL, -1 is used. Returns a stack pointer to the frame if such a 
frame cxists, otherwise rcturns NIL. If opos is supplicd and is a 
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stknth[n;ipos;opos] 


stkname[pos] 
setstkname[pos;name] 


stknthname[n;ipos] 


Stack Functions 


stack pointer, it is reused. If opos is not a stack pointer it is 
ignored. (Note that (STKPOS (QUOTE STKPOS)) causes an error, 
ILLEGAL STACK ARG; it is not permissible to create a stack 
pointer to the active frame.) 


Returns a stack pointer to the nth frame back from the frame 
specified by the stack descriptor ipos. If n is negative, the control 
chain from ipos is followed. If n is positive the access chain is 
followed. If n equals 0, returns a stack pointer to ipos, i.e., this 
provides a way to copy a stack pointer. Returns NIL if there are 


fewer than n frames in the appropriate chain. If opos is supplied 


and is a stack pointer, it is reused. If opos is not a stack pointer it 
is ignored. (Note that (STKNTH 0) causes an error, ILLEGAL 
STACK ARG; it is not possible to create a stack pointer to the active 
frame.) 


Returns the frame name of the frame specified by the stack 
descriptor pos. 


changes the frame name of the frame specified by pos to be name. 
Value is name. 


Returns the frame name of the nth frame back from ipos. 


Equivalent to (STKNAME (STENEN n ipos)) but avoids creation | 


of a stack pointer. 


In summary, stkpos converts function names to stack pointers, stknth converts numbers to stack 
pointers, stkname converts stack роон to function names, and stknthname converts numbers to 


function names. 


dummy framep[pos] 


realframep[pos;interpflg] 


T if the user never wrote write a call to the function at pos, e.g. in 
Interlisp-10, dummyframep is T for "PROG* LAM, *ENV*, and 


- FOOBLOCK frames (see block compiler, Section 18)^ 


is pos, if pos is а "real" frame, i.e. if pos is not a dummy frame, 
and, either pos is a frame that does not disappear when compiled, 


ог  interpflg-zT, otherwise NIL. For example, if 


stkname[pos] = COND, realframep[pos T] 15 Т бшщ 
rcalframcp[pos] = МТ |. 


dummyframep is used by the break package for matching against baktracelst. 
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realstknth[n;pos; ыыр oldpos] 


skips back n (or -n) frames for which rcalframep[pos;interpflg] = T. 


"Thus realframep and realstknth can | be used to write functions which manipulate the stack and 
work on either interpreted or compiled code. 


The following functions are used [ог accessing and changing bindings. Some of functions take an 
argument, n, which specifies a particular binding in the basic frame. If n is a literal atom, it is 
assumed to be the name of a variable bound in the basic frame. If n is a number, it is assumed to- 
reference the nth binding in the basic frame. The first binding is 1. If the basic frame contains no 
binding with the elven name or if the number is too large or too small, the error ILLEGAL ARG 


results, 


stkscan[var;ipos;opos] 
 framescan[atom;pos] — 
| stkarg[n;pos] | 

У stkargname[n;pos] 


sctstkarg[n;pos;value] | 


setstkargname[n;pos;name] | 


stknargs[pos] 


Searches beginning at ipos for a frame in which a variable named 
var is bound. Тһе search follows the access chain. Returns a stack 
pointer to the frame if found, otherwise returns NIL. If opos is a 
Stack pointer it is reused, otherwise it is ignored. z20 


Returns the relative position of the binding of atom in the basic | 
frame of pos. | 


Returns the value of the binding specified by n in the basic frame 


of the frame specified by the stack descriptor pos. n can be a 
literal atom or number. 


. Returns the name of the binding specified by п, in the basic Кате 
of the frame specified by the stack еш pos. п сап be а 


literal atom or number. 


Sets the value of the binding specified by n in the basic frame of 
the frame specified by the stack descriptor pos. n can be а literal 
atom or a number. Returns value. | 


Sets the name ОҒ the binding specified by n in the basic frame of 


the frame specified by the stack descriptor pos. n can be a literal 


atom or a number. Returns name. 


Returns the number of arguments bound in the basic frame of the 
frame specified by the stack descriptor pos. 


As an example of the use of stknargs and stkargname: 


variables[pos] 


returns list of variables bound at pos. 
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can Бе defined by: 


(VARIABLES 
[LAMBDA (POS) 
(PROG (N 1) 


Stack Functions 


(SETO N (STKNARGS POS)) 


LP (COND 


((ZEROP N) 
(RETURN L))) 
(SETQ L (CONS (STKARGNAME М POS) 


L)) 


(SETQ N (SUB1 ШИ 


(СО 1Р1) 


The dual of variables is also available: 


stkargs[pos;-] 


Returns list of values of variables bound at pos. 


The following functions are used to evaluate an expression in a different environment, and/or to 


alter the flow of control. 


| сизот от: ароѕ;сроѕ; aflg: cflg] 


evaluates foni in the environment specified by apos TE cpos. 
That is, a new active frame is created with the frame specified by 
the stack descriptor apos as its alink, and the frame specified by the 
stack descriptor cpos as its clink. Then form is evaluated. If aflg is 
not NIL, and a apos is a stack pointer, then apos will be released. 
Similarly, if cflg is not NIL, and с оз is a stack pointer, then cpos 
will be released. 


envapply[fn; args;apos;cpos; aflg;cflg] 


stkeval[pos;form; flg;-] 


stkapply[pos:fn;args;flg;-] 


reteval[pos; form; flg;-] 


applys fn to args in the environment specified by apos and c cpos. 
aflg and cflg have the same interpretation as with enveval. 


Evaluates form in the access environment of the frame specified by 
the stack descriptor pos. If flg is not NIL and pos is a stack 
pointer, releases pos. Тһе definition of  stkeval і 
(ENVEVAL FORM POS NIL FLG). | 


Similar to stkeval but applics fn to args. 


Evaluates form in the access environment of the frame specified by 
the stack descriptor pos, and then returns from pos with that value. 
If Пр is not NIL and pos is a stack pointer, then pos is released. 
The definition of reteval is equivalent to 
(ENVEVAL FORM POS (STKNTH -1 POS) FLG Т), except 
that reteval docs not create a stack pointer. | 
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retapply[pos; fn;args; flg;-] 


retfrom[pos; val; flg] 


(RETFROM 
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Similar to reteval except applies fn to args. 


Return from the frame specified by the stack descriptor pos, with 
the value val. If flg is not NIL, and pos is a stack pointer, then pos 
is released. An attempt to retfrom the top level (e.g., (RETFROM 
T)) causes an error, ILLEGAL STACK ARG. Retfrom can be 
written in terms of enveval as follows: | 


(LAMBDA (POS VAL ЕЕС) | 
(ENVEVAL (LIST (QUOTE QUOTE). VAL) 


NIL 

(COND | 

((5ТКМТН -4 РО5 (СОКО (FLG Ро5)))) 
(Т (ERRORX (LIST 19 POS))) 


NIL T)) 


retto[pos;val;flg] 


. evalv[x;pos] 


function[fn;env] 


. like retfrom, except returns to frame specified by pos. 


. Evaluates x, where x is assumed to be a litatom, in the access | 


environment specifed by the stack descriptor pos. If x is unbound, 
evalv returns NOBIND and does not generate an error. While evalv 
could be defined as (ENVEVAL X POS) it is in fact a subr which is is 


somewhat faster. evalv- ор open when ро$= NIL. 


If env is NIL, function is equivalent to quote when interpreted and 
is also a signal to the compiler that fn should be compiled. If env 
is a stack pointer, then the value of function is the expression 
(FUNARG fn env). When а funarg expression 15 apply’d or 15 car 


. Of a form being суаГа, the apply or eval takes place in the access 


environment specified by env. For example, if FOO is a funarg 
expression, then (APPLY РОО ЕТЕ) is equivalent to 
(ENVAPPLY (CADR FOO) ЕТЕ (CADDR FOO)). Env can also be 
a list of variable names. In this case, a new frame is created with 
the values of the specified variables in the basic frame. The 
variables are cvaluated in the active access environment (the 
environment of function). The alink of the new frame is the active 
access environment, and clink is the top level. The value of 
function 1s (FUNARG fn pos), where pos is a stack ро to the 
new frame? 


The following functions and variables are used to manipulate stack pointers. 


_ Note that the effect of funarg in the spaghetti system is somewhat different from what it was previously in non- 


spaghetti system. Now when the funarg is apply'd or eval'd we see in the access environment first the variables given 
in the list, and then the access environment at the time the funarg was created. Formerly we saw the variables in the 
list (the "own" variables) and then the access environment at the time Ше funarg was used. 
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stackp[x] 


relstk[pos] 


relstkp[x] 


clearstk[flg] 


clearstklst 


noclearstklst 


Stack Functions 


Returns x if x is a stack pointer, otherwise returns NIL. 


Release the stack pointer pos. If pos is not a stack pointer, does - 
nothing. The value is pos. | | 


returns x is x is a released stack pointer, NIL otherwise. 


If flg is NIL, releases all active stack pointers, and returns NIL. If 
Пр is T, returns а list of all the active (unreleased) stack pointers. - 


Is a (global) variable used by top-level evalgt. Every time evalgt is | 


= re-entered (e.g, following errors, or control-D), clearstklst is 


checked. If its value is T, all active stack pointers are released 

using clearstk. If its value is a list, then all stack pointers on that 
list are released. If its value is NIL, nothing is released. clearstklst 
is initially T. 


is a global variable used by top-level evalgt. If clearstklst is T (see 
above) all active stack pointers except those on noclearstklst are 
released. noclearstklst is вашару NIL. ! 


Thus if one wishes to use multiple environments that survive through control-D, either clearstklst 
should be set to T, or else those stack pointers to be retained should be explicitly added to 


noclearstklst. 


copystk[pos1;pos2] 


Copies the stack, including basic frames, from the frame specified 
by the stack descriptor posl to the frame specified by the stack 
descriptor pos2. That is, copies the frame extensions and basic 
frames in the access chain from pos2 to posl (inclusive). Posl must 
be in the access chain of pos2, 1.е., "above" pos2. Returns the new 
pos2. This provides a way to save an entire environment including 
variable bindings. 


backtrace[ipos;epos; flags; file;printfn] 


Performs a backtrace beginning at the frame specified by the stack 
descriptor ipos, and ending with the frame specified by the stack | 
descriptor epos. flags is a number in which the options of the _ 
backtrace аге encoded. If a bit is set, the corresponding 
information is included in the backtrace. 


bit - print arguments of non-subrs 

bit 1 - print temporaries of the interpreter 

bit 2 - print subr arguments and localvars 

bit 3 - omit printing of UNTRACE: and function names 
bit 4 - follow access chain instcad of control chain. 

bit 5 - print temporaries, i.c. the blips. 
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For example: if Пар5--7, everything is printed; if flags=21Q, follows the access chain, prints 


file is the file that the backtrace is printed to. file must be open. 
printfn is used when printing the values of variables, temporaries, 
blips, etc. oi NIL defaults to PRINT. 


mapdl[mapdifn;mapdipos] . starts at mapdlpos =й applies mapdlfn, a function of two 


arguments, to the function name at each frame, and the frame | | 
(stack pointer) itself, until the top of the stack is reached. Value is 
NIL. 


For exige, mapdl[( LAMBDA (X) (AND (EXPRP X) (PRINT X)))] will print all exprs on 


| the push-down list. 


mapdi[(LAMBDA (X POS) (COND ((IGREATERP (STKNARGS POS) 2) (PRINT УІ 


will print all functions of more than two arguments. 


One ee ы similar to mapdl, except searches the вали list starting at 


position srchpos until it finds a frame for which srchfn, a function | 
of two arguments, applied to the name of the function and the 
frame itself is not NIL. Value is (name . frame) if such a frame 15 
found, otherwise NIL. 


12.4 RELEASING AND REUSING STACK POINTERS 


The creation of a сие stack pointer ‹ can result in the retention of a агре amount of stack space. 
. Furthermore, this space will not be freed until the next garbage collection, even if the stack pointer 
is no longer being used, unless the stack pointer is explicitly released or reused. ТЕ there is 
sufficient amount of stack space tied up in this fashion, a STACK OVERFLOW condition can оссиг, 
even in the simplest of computations. For this rcason, the user should consider releasing a stack 
pointer when the environment referenced by the stack pointer is no longer needed. 


The effects of enl a stack TM are: 


1. Тһе link between the stack pointer and the stack is broken by шш; the contents of 
the stack pointer to the "released mark" (currently unboxed 0). A released stack 
pointer prints as #adr/ #0. 


2. If this stack bomer was the last remaining reference to a frame extension; that is, if no 
other stack pointer references the frame extension and the extension is not contained in 
the active control or access chain, then the extension may be reclaimed, and is 
reclaimed immediately. The process repeats for the access and control chains of the 
reclaimed extension so that all stack space that was rcachable ony from the released 
stack pointer is reclaimed. 


СА Stack pointer may be released using the function relstk, but there are some cases for which relstk 


is not sufficient. For example, if a function contains a call to ге от in which a stack pointer was 
uscd to specify where to return to, it would not be possible to sim to simultaneously release the stack | 


7 pointer. (A relstk appcaring in the function following the call to retfrom would not be executed!) 
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To permit release of a stack pointer in this situation, the stack functions that relinquish control 
have optional flag arguments to denote whether or not a stack pointer is to be released. Note that 
. in this case releasing the stack pointer will not cause the stack space to be reclaimed immediately 
because the frame referenced by the stack pointer will have become part of the active environment. 


REUSING STACK POINTERS 


Another way of avoiding creating new stack pointers is to reuse stack pointers that are no longer 
needed. The stack functions that create stack pointers (stkpos, stknth, and stkscan) have an 
optional argument which is a stack pointer to reuse. When a stack pointer is reused, two things 
happen. First the stack pointer is released (see above). Then the pointer to the new frame 
extension is deposited in the stack pointer. The old stack pointer (with its new contents) is the 
value of the function. Note that the reused stack pointer will be released even if the function does 
not find the specified frame. 


Note that even if stack pointers are explicitly being released, creation of many stack pointers can 
cause a garbage collection of stack pointer space. Thus, if the user's application requires creating 
many stack pointers, he definitely should take advantage of reusing stack pointers. 


12.5 COROUTINES AND GENERATORS? 


This section describes an application of the spaghetti stack facility to provide mechanisms for 
creating and using simple generators (with and without CLISP, Section 23), generalized coroutines, 
and Conniver style possibility lists. | 


А generator is like a subroutine except that it retains information about previous times it has been 
called. Some of this state may be data (for example, the seed in a random number generator), and | 
some may be in program state (as in a recursive generator which finds all the atoms in a list 
structure). For example, if listgen is defined using defineq as: 


(LISTGEN (L) 
(IF L THEN (PRODUCE L:1) (LISTGEN L::1))) 


we can use the function generator (described below) to create a ere that uses listgen to 
produce the elements of a list one at a time, e.g., 


GRe(GENERATOR (LISTGEN "(АВ C)) 
creates a generator, which can be called by 
(GENERATE GR) 
to produce as values on successive calls, A, B, C. When generate (not generator) is called the first 


time, it simply starts evaluating (LISTGEN "(АВ C)). produce gets called from listgen, and | 
pops back up to generate with the indicated value after saving the state. When generate gets called 


Designed and implemented by D.G. Bobrow, who also did the documentation. Farly versions of the Conniver 
possibilites-list package were written by Henry Thompson. Daryle Lewis found and corrected a number of bugs, and 
wrote the compiler macros that go with the package. | | 
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again, it continues from where the last produce left off. This process continues until finally listgen | 
completes and returns a value (it doesn’t matter what it is). generate then returns gr itself as its 
value, so that the program that called generate can tell that it is finished, i.e., there are no more 
values to be generated. | 


generator[form # # :comvar # #1 
is ап nlambda function that creates а generator which uses 
form# # to compute values. The value of generator is a generator 
handle which is represented by a dotted pair of stack pointers. 


comvar# # is optional. If its value (eval of) is a generator handle, 
the list structure and stack pointers will be reused. Otherwise, a 
new generator handle will be constructed. 

generator compiles open. 


produce[val] | is used from within (below) a generator to return val as the value of 
"LN . the corresponding call to generate. 


generate[handle;val] . restarts the generator represented by handle. val will be returned 


as the value of the produce which last suspended the operation of 
the generator. When the generator runs out of values, generate 
returns handle itself. | 


EXAMPLES. 


The юле function will go down recursively through а ist structure and produce the atoms in 
the list structure one at a time. 


[LEAVESG (L) 
(if (ATOM L) 
then (PRODUCE L) 
else (LEAVESG L:1) 
CIT Поза 
then (LEAVESG L::1] 


The following function prints each of these atoms as it appears. It illustrates how a loop can Ве set 
up to use a generator. 


(PLEAVESG1 (L) 
(PROG (X LHANDLE) 
(LHANDLE-(GENERATOR (LEAVESG L))) 
LP — (Xe(GENERATE LHANDLE)) 
(if X=LHANDLE 
then (RETURN NIL)) 
(PRINT X) 
(60 LP))) 


.. Note that the loop terminates when the value of the gencrator is eq to the dotted pair which is the | 


value produced by Ше call to generator. А CLISP iterative operator, OUTOF, is provided which 
12.14 


Coroutines and Generators > 


makes it much easier to write the loop іп PLEAVESG1. OUTOF (or outof) can precede а form 
which is to be used as a generator. On each iteration, the iteration variable will be set to 

. successive values returned by the generator; the loop will be terminated automatically when Ше 
generator runs out. Thus we can write 


(PLEAVESG2 (L) 
(for X outof (LEAVESG L) do (PRINT x)) 


as equivalent to the above program PLEAVESG1. 
Here is another Е 


(for Х outof (MAPATOMS (FUNCTION PRODUCE) ) 
as I from 1 to N do (PRINT X)) 


will print the first n atoms. 


COROUTINES 


This package provides facilities for the creation and use of fully general coroutine structures. It 
uses a stack pointer to preserve the state of a coroutine, and allows arbitrary switching between n 

- different coroutines, rather than just a call to a generator and return. This package is slightly more 
efficient than the generator package described above, and allows more Неру оп specification of 
what to do when a coroutine terminates, | 


согомвіле(сайріг” # ;coroutptr # # ;coroutform# # -endform # #] 

This nlambda is used to create a coroutine and initialize the 
linkage. callptr## and coroutptrZ # аге the names of two 
variables, which will be set to appropriate stack pointers. If the 
values of callptr# # or coroutptr Z # are already stack pointers, the 
stack pointers will be reused. coroutform# # is the form which is 
evaluated to start the coroutine; endform# # is a form to be 
evaluated if coroutform # # actually returns when it runs out of 
values. 


coroutine compiles open. 


resume[fromptr;toptr; val] is used to transfer control from one coroutine to another. fromptr 
should be the stack pointer for the current coroutine, which will be 
smashed to preserve the current state. toptr should be the stack 
pointer which has preserved the state of the coroutine to be 7 
transferred to, and val is the value that is to bc returned to the 
latter coroutine as the value of the resume which suspended the 
operation of that coroutine. 


EXAMPLES 
. The following is the way one might write the LEAVES program using the coroutine package: 


(LEAVESC (L COROUTPTR CALLPTR) 
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(if (ATOM L) then (RESUME COROUTPTR CALLPTR L) 
else (LEAVESC L:1 COROUTPTR CALLPTR) 
— (if L::1 then (LEAVESC L::1 COROUTPTR CALLPTR)))) 


A function PLEAVESC which uses LEAVESC can be defined as follows: 


(PLEAVESC (L) 
С (bind PLHANDLE LHANDLE first (COROUTINE PLHANDLE LHANDLE 
| (LEAVESC L LHANDLE PLHANDLE) 
(RETFROM 'PLEAVESC)) 
do (PRINT (RESUME PLHANDLE LHANDLE)))) 


Ву RESUMEing leavesc repeatedly, this function will print all the leaves of list L and then return 
out of pleavesc via the retfrom. Тһе retfrom is necessary to break out of the non-terminating do- 
loop. This was done to illustrate the additional flexibility allowed through the use of endform #. 


We use two coroutines working on two trees іп the example eqleaves, defined below. egleaves tests 
to see whether two trees have the same leaf set in the same order, eg, 
EQLEAVES((A B C)(A B (C))) is true. 


(EQLEAVES (L1 L2) 
(bind LHANDLE1 LHANDLE2 РЕ EL1 EL2 
first (COROUTINE PE LHANDLE1 (LEAVESC L1 LHANDLE1 PE) 'NO-MORE) 
(COROUTINE PE LHANDLE2 (LEAVESC L2 LHANDLE2 PE) 'NO-MORE) 
до (EL1«(RESUME PE LHANDLE1)) 
(EL2«(RESUME PE БИМЕН 562) 
(if EL1~=EL2 | 
then (RETURN NIL)) 
repeatuntil EL1="NO-MORE finally (RETURN T))) 


POSSIBILITIES LISTS’ 


A possibilities list is the interface between a generator and a consumer. The possibilities list is 
initialized by a call to possibilities, and elements are obtained from it by using trynext. By using 
the spaghetti stack to maintain separate environments, this package allows a regime in which a 
generator can put a few items in a possibilities list, suspend itself until they have been consumed, 
апа be subsequently aroused and generate some more. 


possibilitics[ form # #] This nlambda is used for the initial creation of a possibilities list. 
| | form# # will be evaluated to create the list, It should use Ше 
functions note and au-revoir described below to generate 
possibilities. ^ Normally, one would sct some variable to Ше 

possibilities list which is returned, so it can be used later, e.g.,: 


(SETQ PLIST (POSSIBILITIES (GENERFN V1 V2))). 


possibilities compiles open. 


These functions are based on the CONNIVER system possibilities list package. 
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note[val;Istflg] 


au-revoir[val #] 


adieu[val # #] 


Coroutines and Generators 


is used within a generator to put items on the possibilities list being 
generated. If Istflg is equal to NIL, val is treated as a single item. 
If Istflg is non-NIL, then the list val is nconced on the end of the 
possibilities list. Note that it is perfectly reasonable to create a 
possibilities list using a second generator, and note that list as 
possibilities for the current generator with Istflg equal to Т. The 

lower generator will be resumed at the appropriate point. | 


puts val # оп the possibilities list if it is given? and then 
suspends the generator and returns to the consumer in such a 
fashion that control will return to the generator at the au-revoir if 
the consumer exhausts the possibilities list. 


like au-revoir except releases the generator instead of suspending it. 


trynext[plst # # ;endform # #;val# #] 


cleanposlst[plst] 


EXAMPLE 


This nlambda на a consumer to use а possibilities list. It 
removes the first item from the possibilities list named by plst# Ж 
(i.e. plst# Ж must be an atom whose value is a possiblities list), and 
returns that item, provided it is not a generator handle. If a 
generator handle is encountered, the generator is reawakened. 
When it returns a possibilities list, this list is added to the front of 
the current list. When а call to trynext causes a generator to Бе. 
awakened, уа # is returned as the value of the au-revoir which 
put that generator to sleep. If plst## is empty, it evaluates | 


 endform Z # in the caller’s environment. 


trynext compiles open. 


This function is provided to release any stack pointers which may 
be left in the plst which was not used to exhaustion. 


fib is a generator for fibonnaci numbers. It starts out by noteing its two arguments, then suspends 
itself. Thereafter, on being re-awakened, it will note two more terms in the series and suspends 
again. printfib uses fib to print the first N fibonacci cci numbers. — 


8 


NIL is not put on the possibilities list unless it is explicitly given as an argument to au-revoir, i.e., au-revoir[] and 


au-revoir[NIL] are пог the same. au-revoir and adieu are lambda spreads to enable them to distinguish these two 


cases. 
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= [FIB (F1 F2) | 
|. (do (NOTE F1) 
| (МОТЕ Е2) 
(F1eF1+F2) 
(F2eF1+F2) 
(AU-REVOIR) ]? 
ГРАТМТЕТВ (М) 
(PROG ((FL (POSSIBILITIES (FIB 0 1)))) 
-~  (RPTQ М (PRINT (TRYNEXT Е1))). 
 (CLEANPOSLST FL) ] | 


. Note that fib itself will never terminate. 


d Note that this au-revoir just suspends the generator and adds nothing to the possibilities list except the generator. 
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SECTION 13 
NUMBERS AND ARITHMETIC FUNCTIONS 


There are three different types of numbers in Interlisp: small integers, large integers, and floating 
point numbers.! Since a large integer or floating point number can be (in value) any full word 
quantity (and vice versa), it is necessary to distinguish between those full word quantities that 
represent large integers or floating point numbers, and other Interlisp pointers. We do this by 
"boxing" the number, which is sort of like a special "cons": when a large integer or floating point 
number is created (via an arithmetic operation or by read), Interlisp gets a new word from 
"number storage" and puts the large integer or floating point number into that word. Interlisp 
then passes around the pointer to that word, i.e., the "boxed number", rather than the actual 
quantity itself. ‘Then when a numeric function needs the actual numeric quantity, it performs the 
extra level of addressing to obtain the "value" of the number. This latter process is called 
“unboxing”. Note that unboxing does not use any storage, but that each boxing operation uses 
one new word of number storage. Thus, if a computation creates many large integers or floating 
point numbers, i.e., does lots of boxes, it may cause a garbage collection of large integer space, or 
of floating point number space. | 


13.1 INTEGER ARITHMETIC 
SMALL INTEGERS 


Small integers are those integers for which smallp is true. In Interlisp-10, these are integers whose 
absolute value is less than 1536. Small integers are boxed by offsetting them by a constant so that 
they overlay an area of Interlisp’s address space that does not correspond to any Interlisp data type. 
Thus boxing small numbers does not use any storage, and furthermore, each small number has a 
unique representation, so that eq may be used to check equality. Note that eq should not be used 
for large integers or floating point numbers, e.g., in Interlisp-10, eq[2000;add1[1999]] is NIL! едр, 
ісар, or equal must be used instead. 


1 Floating point numbers are created by the read program when а. ог ап E appears їп a number, e.g., 1000 is ап 
integer, 1000. a floating point number, as are 1E3 and 1.E3. Note that 1000D, 1000F, and 1E3D are perfectly 
legal literal atoms. 

2 


Different implementations of Interlisp-10 may use different boxing strategies. Thus, while lots of arithmetic 
opcrations may lcad to garbage collections, this is not necessarily always the case. 
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INTEGER FUNCTIONS 


All of the functions described below work on integers. Unless specified otherwise, if given a 
floating point number, they first convert the number to an integer by truncating the fractional bits, 
ер. iplus[2.3;3.8]=5; if given a non-numeric argument, they generate an error, NON-NUMERIC 
ARG. 


It is important to use the integer arithmetic functions, whenever possible, in place of the more 
general arithmetic functions which allow mixed floating point and integer arithmetic, e.g., iplus vs 
plus, igreaterp vs greaterp, because the integer functions compile open, and therefore run faster 
than the general arithmetic functiors, and because the compiler is "smart" about eliminating - 
unnecessary boxing and unboxing. In other words, if the value of an integer arithmetic function is 
being used in arithmetic context, i.e. as an argument to another arithmetic function, no boxing ог 


unboxing will be performed. Thus, the J expression 
(IPLUS (IQUOTIENT (ITIMES N 100) M) (ITIMES X Y)) will compile to perform only 
one box, the outer one, and the expression 


(IGREATERP (IPLUS X Y) (IDIFFERENCE A B)) will compile to do no boxing at all. The 
compiler also treats a conditional expression all of whose values are integer functions the same as 
an arithmetic function, e.g. (IPLUS X (COND (FOO (ITIMES A B)) (T (ITIMES C D)))) 
will produce only one box, the outer one. 


Note that the PDP-10 is a 36 bit machine, so that in Шейше -10 all integers are between -2135 and 
2135-1? Adding two integers which produce a result outside this range causes overflow, е. 8., 2134 
+ 2134. 


. The procedure on overflow is to return the largest possible integer, i.e., in Interlisp-10 2135 - 1.4 


пир ко: ко] | X] + ху +... + ху. iplus[]=0. 


iminus[x] ; X 
idifference[x;y] х-у 
айах]. | xc 1 
| subl [x] | х-1 
itimes[x] :x2;... x] | _ the product of xjx»,...xn. itimes[] = 1. 


Approximately 34 billion 


If the overflow occurs by trying to create a negative number of too large a magnitude, -2135+1 is used instead of 
2135-1. 
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iquotient[x;y] 


iremainder[x Э] 
igreaterp[x;y] 
ilessp[x;y] 
igeg[x;y] | 


ileq[x;y] 


imin[x];x5;..; x] | 


ж 


аруа] 


ieqp[n;m] 


zetop[x] 


Integer Arithmetic 


x/y truncated, c.g., iquotient[3;2] — 1, 
iquotient[-3,2] =- 


the remainder when x is divided by y, e.g., iremainder [3;2]=1 


T, ifx > y; NIL otherwise. 


— 


T,ifx € у; NIL otherwise. 


T,ifx > у; NIL otherwise. 


T,ifx < у; NIL otherwise. 


valde is ‘minimum ОЁ xj, X5, Ха. imin[] returns the smallest | 


possible integer, the valuc of min. integer.” Does not compile open. 


value is maximum of Xp X5, Xp imax[] returns the largest 
possible Integer, the value of max. | integer. Does not compile open. 


T, if n and m are eq, or equal integers, NIL otherwise. Note that eq 
may be used if n and m are known to be small integers. ieqp 


converts n and m to integers, e.g., icqp[2000;2000.3] = T, causes 


NON-NUMERIC ARG error if either n or m are not numbers. ieqp 
compiles open. 


defined as eg[x;0]. 


Nöte that zerop should not be used for floating point numbers because it uses eg. Use сарјх; `0] 


instead. 


minusp[x] 


eqp[n;m] 


T if x is negative; NIL otherwise. Does not convert x to an integer, 
but simply checks sign bit. 


T, if n and m are eq, or equal numbers, NIL otherwisc.Ó Note that 
са may Бе used if n and m are known to be small integers. egp 


In other words, if x is ап integer, then x > min integer. 


сар is also T if n and m are both stack descriptors that refer to the same frame extension (see Section 12). 
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++ 


++ 


smallp[n] 


fixp[x] 


fix[x] 


Іорапа[хү;х2;...5х | 


logor[x :x2;...:x g] 


logxor[x1;x5;...;x] | 


Ish[n;m] 
rsh[n;m] 
Ilsh[n;m] 


Irsh[n;m] 


called. 
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does not convert п and m to integers, e.g., eqp[2000;2000.3] = NIL, 
but it can be used to compare an integer and a floating point 
number, c.g., eqp[2000;2000.0] 2 T. еар does not generate an error 
if n or m are not numbers. 


n, if n is a small integer, else NIL. smallp does not generate an 
error if n is not a number. | 


x, if x is an integer, else NIL. Does not generate an error if x is 


not a “number. 


Converts x to an integer by truncating fractional bits, e.g. 
fix[2.3] = 2, fix[-1.7] =_-1. Ifx is already an integer, fix[x]=x and 
doesn't use any storage. 


lambda no-spread, value is logical and of all its arguments, as an 
integer, e.g., logand[7;5;6]=4. 


lambda no-spread, value is the logical or of all its arguments, as an 


integer, e.g., logor[1;3;9]— 11. 


lambda no-spread, value is the logical exclusive or of its arguments, 
as an integer, e.g., logxor[11;5] — 14, 
logxor[11;5;9] = logxor[14;9] = 7. 


(arithmetic) left shift, value is n*2tm,i.e., n is shifted left m places. 
n can be positive or negative. If m is negative, n is shifted | right -m 
places. 


(arithmetic) right shift, value is n*2t-m, i.e., n is shifted right m 
places. n сап be positive or negative. If m is negative, n is left -m 
places. 


logical left shift. On PDP-10, Ilsh is equivalent to Ish. 


logical right shift. 


Since FIX is also a lispx command (Section 22), typing FIX directly to lispx will not cause the function fix to be 
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Integer Arithmetic 


The difference between a logical and arithmetic right shift lies in the treatment of the sign bit for 
negative numbers. For arithmetic right shifling of negative numbers, the sign bit is propagated, 

"је. the value is a negative number. For logical right shift, zeroes are propagated. Note that 
shifting (arithmetic) a negative number "all the way" to the right yields -1, not 0. 


gcd[x;y] | value is the greatest common divisor of x and y, e.g., gcd[72;64] — 8. 


13.2 FLOATING POINT ARITHMETIC 


АП of the functions described below work on floating point numbers. Unless specified otherwise, if 
given an integer, they first convert the number to а floating point number, e.g. 
fplus[1;2.3] = fplus[1.0;2.3] = 3.3; if given а non-numeric argument, they generate an error, NON- 
NUMERIC ARG. | | 


The largest floating point number (in Interlisp-10) is 1.7014118E38, the smallest positive (non-zero) 
floating point number is 1.4693679E-39. The procedure on overflow is the same as for integer 
arithmetic. For underflow, i.e., trying to create a number of too small a magnitude, the value will 


be 0. 

fplus[x);x9;...X,] X] + Хо + - + Xn 

fminus[x] -X 

fdifference[x;y] х-у 

ftimes[x у;хә;...;х„] Ky *ху*..*х„ 

fquotient[x ; y] x/y 

fremainder[x;y] the remainder when x is divided by у, іш * 
fdifference[x;ftimes[y;fix[fquotient[x ;y]]]], e.g. fremainder[7.5;2.3]=.6. * 

minusp[x] T, if x is negative; NIL otherwise. Works for both integers and 
floating point numbers. | 

едр[х;у] T, if x and у аге са, or equal numbers. See discussion page 13.3. 

fgreaterp[x;y] T, if x > у, NIL otherwise, 

flessp[x;y] T, if x < y, NIL otherwise. T 
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+ fmin[x];x9;...3x,] value is minimum of xj, x5, .. Xp fmin[] returns the smallest 
+ иб possible floating point number, the value of min.float. 
fmax[x1:x2;...;x] value is maximum ОҒ xj, x5, . . fmax[] returns the largest 
| | possible floating point number, the E ue of max.float. 
flotp[x] | С ds x if x is a floating point number; NIL otherwise. Does not give 
an error if x is not a number. 
Note that if numberp[x] is true, then either fixp[x] or floatp[x] is true. 
float[x] | Converts x to a floating point number, e.g., float{0] = 0.0. 
13.3 MIXED ARITHMETIC 
The functions in this section are “contagious floating point arithmetic" functions, i.e., if any of the 
arguments are floating point numbers, they act exactly like floating point functions, and float all 
arguments, and return a floating point number as their value. Otherwise, they act like the integer 
2 functions. If given а non- numeric argument, ч generate an error, NON- NUMERIC ARG. 
 plusxpxonoxgho О кү+ху+ + Xp 
minus[x] — | "X 
difference[x;y] х-у 
times[x :x5;...:x] KI хә... Xa 
quotient[x;y] if x and y are both integers, value is iquotient[x;y], otherwise 
| fquotient[x;y]. | | 
B remainder[x;y] “| if x and y are both integers, value is iremainder[x;y], за Шай 
| | Кетатдејкуј | | 
greaterp[x;y] | T, if x > y, NIL otherwise. 
"Тек. T if x < у, NIL otherwise. 
55 geg[x;y] | |. T,ifx > y, NIL otherwise. 
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leg[x;y] — T, if x Су, NIL otherwise. E + 


min[x |;X5;...;Xg] value is minimum of zp Ху, -- Хр. min[] returns the value of 
min.integer. 


++ 


тах[х1;хэ;...;Хх] value is maximum of xj, X5, ..‚ Ха. max[] returns the value of 
max integer. 


++ 


abs[x] x if x > 0, otherwise -x. abs uses greaterp and minus, (not 
igreaterp and iminus). 


13.4 SPECIAL FUNCTIONS? 


They utilize a power series expansion and their values are (supposed to be) 27 bits accurate, e.g., 
sin[30] 2.5 exactly. | 


expt[m;n] value is mtn. If m is an integer and n is a positive integer, value is 
an integer, e.g, expt[3; :4] = 81, otherwise the value is a floating point 
number. If m is negative and n fractional, an error is generated, 
ILLEGAL EXPONENTIATION. If n is floating and either too large 
or too small, an error is generated, VALUE OUT OF RANGE EXPT. 


Tc 


 Sqrit[n] value is a square root of n as a floating point number. n may be 
fixed or floating point. Generates an error if n is negative. sqrt[n] 
is about twice as fast as expt[n;.5] 


log[x] value is natural logarithm of x as a floating point number. x can 
be integer or floating point. 


antilog[x] value is floating point number whose logarithm is x. x can be 
integer or floating point, e.g., antilog[1] = e = 2.71828... 


sin[x ;radiansflg] x in degrees unless radiansflg=T. Value is sine of x as а floating 
point number. | 


cos[x;radiansflg] Similar to sin. 


In Interlisp-10, these functions were implemented by J. W. Goodwin by "borrowing" the corresponding routines 
from the FORTRAN library, and hand coding them in Interlisp-10 via ASSEMBLE, 
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tan[x;radiansflg] 


| arcsin[x;radiansflg] 


arccos[x;radiansflg] 
arctan[x;radiansflg] 


arctan2[x;y;radiansflg] 


rand[lower;upper] 


. randset[x] 
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Similar to sin. 


x is a number between -1 and 1 (or an error is generated). The 
value of arcsin is a floating point number, and is in degrees unless 
radiansflg 2 T. In other words, if arcsin[x;radiansflg]-z then 
sin[z;radiansflg] 2x. The range of the value of arcsin is -90 to --90 2 
for degrees, -т/2 to т/2 for radians. | 


Similar to arcsin. Range is 0 to 180, 0 to т. 
Similar to arcsin. Range is 0 to 180, 0 to " 


computes | arctan[[fquotient[x;y];radiansflgl] and returns а 
corresponding value in the range -180 to 180 (or -pi to pi), i.e. the 
result is in the proper quadrant as determined by the signs of x an 
у, | | 


 » Value is а pseudo-random number between lower and upper 
inclusive, i.e., rand can be used to generate a sequence of random 
numbers. If both limits are integers, the value of rand is an 
integer, otherwise it is a floating point number. The algorithm is 


. completely deterministic, ie. given the same initial state, rand | 


produces the same sequence of values. The internal state of rand is 
initialized using the function randset described below. 


Value is internal state of rand after randset has finished operating. 
If x - NIL, value is current state. If x=T, randstate is initialized 
using the clocks. Otherwise, x is interpreted as a previous internal 
state, ie. a value of randset, and is used to reset randstate. For 
example, | E | 
l. (SETQ OLDSTATE (RANDSET)) 

2. Use гапа to generate some random numbers. 
3. (RANDSET OLDSTATE) 

4. rand will generate same sequence as іп 2. 


13.5 REUSING BOXED NUMBERS IN INTERLISP-10 - SETN 


rplaca and rplacd provide a way of cannibalizing list structure for reuse in order to avoid making 
new structure and causing garbage collections.” This section describes an analogous function in 


The nobox package (Section 24) provides a more aesthetic way of reusing cons cells as well as number boxes. 


However, it is still the case that techniques involving reusing static storage should be used with extreme caution, and 
be reserved for those cases wherc the normal method of storage allocation and garbage collection is not workable of 
practical. The дес! package (Section 24) takes a different approach to the same problem by avoiding creating number 
boxes in the first place via type declarations in the body of the function definition. 
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Reusing Boxed Numbers іп Interlisp-10 - SETN 


Interlisp-10 for reusing large integers and floating point numbers, setn. setn is used like setq, i.e., 
its first argument is considered as quoted, its second is evaluated. If the current value of the 

variable being set is a large integer or floating point, mper, the new value is deposited into that 
word in number storage, i.e., по new.storage is used.! If the current value is not a large integer or 
floating point number, c.g., it can be NIL, setn operates exactly like setq, і.е., the large integer or 
floating point number is boxed, and the variable is set. This eliminates initialization of the 
variable. | 


өсіп will work interpretively, i.e., reuse а word in number storage, but will not yield any savings of 
storage because the boxing of the second argument will still take place, when it is evaluated. The 
climination of a box is achieved only when the call to setn is compiled, since setn compiles open, 
and does not perform the box if the old value of the variable can be reused. 


CAVEATS CONCERNING USE OF SETN 


There are three situations to watch out for when using setn. The first occurs when the same 
variable is being used for floating point numbers and large integers. If the current value of the 
variable is a floating point number, and it is reset to a large integer, via setn, the large integer is 
simply deposited into a word in floating point number storage, and hence will be interpreted as a 
floating point number. Thus, | | 


«(5ЕТ0 FOO 2.3) 
2.3 

–(ЗЕТМ FOO 10000) 
2.189529Е-43 


Similarly, if the current value is a large integer, and the new Bc is a floating point number, 
equally strange results occur. | 


The second situation occurs when а setn variable is reset from a large integer to a small integer. Іп 
this case, the small integer is simply deposited into large integer storage. It will then print 
correctly, and function arithmetically correctly, but it is not a small integer, and hence will not be 
eq to another integer of the same value, e.g., | 


«(5ЕТ0 FOO 10000) 
10000 

«(5ЕТМ FOO 1) 

1 


«(ІРІМ5 ЕОО 5) 
6 

«(EQ FOO 1) 
NIL 

-(SMALLP FOO) 
NIL 


In particular, note that zerop will return NIL even if the variable is equal to 0. Thus a program 
which begins with foo set to а large integer and counts it down by 
(SETN FOO (SUB1 ЕОО)) must terminate with (EQP FOO 0), not (ZEROP ЕОО). | 


10 


The sccond argument to өсіп must always be a number or а NON-NUMERIC ARG error is generated. 
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Finally, the third situation to watch out for occurs when you want to save the current value of a 


өсіп variable for later use. For example, if foo is being used by setn, and the user wants to save its 


current value on fic, (SETQ FOO ЕТЕ) is not sufficent, since the next өсіп on foo will also change 


Не, because its changes the word in number storage pointed to by foo, and hence pointed to by fie. 
The number must be copied, е.2., (5ЕТО ЕТЕ (I PLUS FOO)), which sets fie to a new word in 
number storage. 


setn[vanx] |. -- » nlambda function like setq. var is quoted, х is evaluated, and its 
| 1 value must be a number. var will be set to this number. If the 
current value of var is a large integer or floating point number, that 
word in number storage is cannibalized. The value of setn is the 

(new) value of var. 


13.6 BOX AND UNBOX IN INTERLISP-10 


Some applications may require that а user program explicitly perform the boxing and unboxing 


operations that are usually implicit (and invisible) to most programs. The functions that perform 
these operations are loc and vag respectively. For example, if a user program executes a ТЕМЕХ 
JSYS using the ASSEMBLE directive, the value of the ASSEMBLE expression will have to be boxed 
to be used arithmetically, e.g. (IPLUS X (LOC (ASSEMBLE --))). It must be emphasized 
that 


Arbitrary ios numbers should not be passed around as ordinary values because they can cause 


trouble for the garbage collector. 


For example, suppose the. value of x were 150000, and you created (VAG X), and this just 


happened to be an address on the free storage list. The next garbage collection could be disastrous. 
For this reason, the function vag must be used with extreme caution when its argument’ $ range is 
not known. | 


loc is the inverse of vag. It takes ап address, i.e., а 36 bit quantity, and treats it as a number and | 
boxes it. For example, loc of an atom, e.g., (LOC (QUOTE ЕОО)), treats the atom as а 36 bit. 


quantity, and makes a number out of it. If the address of the atom FOO were 125000, 


(LOC (QUOTE F00)) would be 125000, i.e., the location of FOO. It is for this reason that the 
box operation is called loc, which is short for location. 


Note that FOO does not print as #364110 (125000 in octal) because the print routine recognizes 


that it is an atom, and therefore prints it in a special way, i.e., by printing the individual characters 
that comprise it. Thus (VAG 125000) would print as FOO, and would in fact be FOO. 


loc[x] Makes a number out of x, i.e., returns the location of x. 


E vag is an abbreviation of value get. 
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Box and Unbox in Interlisp-10 
vag[x] The inverse of loc. x must be a number; the value of vag is the 
unbox of x. 


The compiler eliminates extra vag's and loc's for example (IPLUS X (LOC (ASSEMBLE --))) 
will not box the value of the ASSEMBLE, and then unbox it for the addition. | 
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SECTION 14 
INPUT/OUTPUT FUNCTIONS 


14.1 FILES 


All input/output functions in Interlisp can specify their source/destination file with an optional 
extra argument which is the name of the file. This file must be opened as specified below. If the 
extra argument is not given (has value NIL), the file specified as "primary" for input (output) is 
used. Normally these are both T, for terminal input and output. However, the primary 
input/output file may be changed by | 


input[file]! Sets file as the primary input file. Its value is the name of the old 
primary input file. | 


input[] returns current primary input Ме, which is not changed. - | 
output[file] Same as input except operates on primary output file. 


Any file which is made primary must have been previously opened for input/output, except for the 
file T, which is always open. | 


infile[file] | Opens file for input, and sets it as the primary input file. The 
| value of infile is the previous primary input file. If file is already 
open, same as три Неј. Generates a FILE WON'T OPEN error if 

file won't open, e.g., file is already open for output. 


1 The argument name file is used for tutorial purposes only. 54015 do not have argument "names", per se, as 


input opcrations referring to the primary input file will obtain characters from that string. 


2 To open file without changing the primary input file, perform openfilc[file; INPUT]. 
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. ош еј еј Opens file for output, and sets it as the primary output file? The 


value of outfile is the previous primary output file. If file is already 
open, same as output[fileJ. Generates а FILE WON'T OPEN error 
if file won't open, e.g., if file is already open for input. 


In Interlisp-10, for all input/output functions, file follows the TENEX^ conventions for file names, 
ie. file can be prefixed by a directory name enclosed in angle brackets, can contain < esc» s or 
control-F's, and can include suffixes and/or version numbers. When a file is opened for input and 
no version number is given, the highest version number is used. Similarly, when a Ме is opened 
for output and no version number is given, a new file is created with a version number опе higher 
than the highest one currently in use with that file name. | 


Іп Interlisp-10, regardless of the Ше name given to the Interlisp function that opened the file, 
Interlisp maintains only full file names? in its internal table of open files and any function whose 
value is a file name always returns a full file name, e.g., openp[ FOO ]=<TEITELMAN>FOO. :3. 
Whenever a file argument is given to an i/o function, Interlisp first checks to see if the file is in its 
internal table. If not, Interlisp executes the appropriate JSYS to "recognize" the file. If the 


| opa anng system does not successfully recognize the file, a FILE NOT FOUND error is generated. 


7 ff it does recognize the file, it returns to Interlisp the full file name. Then, Interlisp can continue 
with the indicated operation. If the file is being opened, Interlisp opens the file and stores its (full) 
name in the file table. If it is being closed, or written to or read from, Interlisp checks its internal 
table to make sure the file is open, and then executes the corresponding operation. | 


Note that each time a full file name 15 по! used, Interlisp-10 must call the operating system to 
recognize the name. Thus if repeated operations are to be performed, it is considerably more 
efficient to obtain the full file name once, e.g., via іп ер or ош ер. Also, note that recognition is 
performed on the user’s entire directory. Thus, even if only one file is open, say FOO.;1, Е5 
(F altmode) will not be recognized if the user’s directory also contains the file FIE.;1. Similarly, 


= it is possible for a file name that was previously recognized to become ambiguous. For example, a 


++ 


+ + + 


program performs infile[FOO], opening Ғ00.;1, and reads several expressions from FOO. Then 
the user types control-C, creates а FOO. ; 2 and reenters his program. Now а call to read giving И. 
FOO as its file argument will generate a F ILE NOT OPEN error, because FOO will be recognized as 
FOO. ;2. | 


 infilep[file] | . Returns full Ме name of Ме if file is recognized as specifying the 


name of a file that can be opened for input, NIL otherwise. 
Recognition is in input context, ie. іп Interlisp-10, if no version 
number is given, the highest version number is returned. 


3 To open file without changing the primary output file, perform openfile[file; OUTPUT]. 

4 AS inentionéd in chapter 2, Interlisp-10 also runs under the TOPS-20 operating system. In this case, file follows the 
TOPS-20 conventions. 

5 i.e., directory name, extension, and version. 

6 except for infilep, outfilep and openp, which in this case return NIL. 


As described in Section 16, before the actual error occurs, it is intercepted ма an entry on errortypelst, which causes 
зрей Ше (Section 17) to be called. өре Піс will search alternate directories and possibly attempt spelling correction оп 
the file name. Only if spellfile is unsuccessful will the error actually occur. - 
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infilep and ош Шер do not open any files, or change the primary files; they are pure predicates. 


| outfilep[file] 


Similar to infilep, except recognition is in output context, i.e., in 
Interlisp-10, if no version number is given, a version number one 
higher than the highest version number is returned. 


A more general version of infilep and outfilep is provided by the function fullname: 


. fullname[x;recog] 


If x is recognized in the recognition mode specified by recog as an 
abbreviation for some file, value is the file's full name, otherwise 
NIL. recog can be OLD, NEW, OLDEST, or OLD/NEW.8 
recog = NIL defaults to OLD. For all other values, generates ап 
error ILLEGAL ARG. If x is not a literal atom, generates an error, 
ARG NOT LITATOM. 


For example, infilep[file] could be written as fullname[file; OLD] and 


. outfilep[file] as fullname[file;NEW]. 


A more general way of opening files is provided by the function openfile: 


openfile[file;access;recog; че machine.dependent.parameters] 


Opens file with access rights as specified by access, one of INPUT, 


OUTPUT, BOTH, or APPEND. file is first recognized (in the | 


fullname sense) using recognition mode recog. If recog=NIL, it 
defaults according to the value of access: for access= INPUT, 
гесор —OLD is used; for access=OUTPUT, гесор = NEW is used; for 
the other values of access, recog = OLD/NEW is used. If file cannot 
be recognized generates a FILE NOT FOUND error? Does not 
affect primary input or output files. и 


For ехатріе, infile[file] is equivalent ко 
input[openfile[file; INPUT;OLD]]  outfile[file] is equivalent to 
output[openfile[file; QUT PUT;NEW]]. | 


bytesize, if supplied, is the byte size in which to open the file (if 


bytesize = NIL, 7 is used). machine.dependent.parameters is a list of | 


additional opening parameters. Interlisp-10 currently recognizes the 
following values: 


WAIT wait if Ме is busy. 
DON'T.CHANGE.DATE don't change the access dates. 


OLD/NEW means if recognition fails using OLD, then use NEW (useful only for writing a file). 


Various other errors may be generated in Interlisp-10 if the file cannot be opened, e.g. FILE WONT OPEN if the file 


is already opened by somcone else, FILE SYSTEM RESOURCES EXCEEDED if thcre is no more room in the file 
System. See Section 16 for further discussion. 
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openp[file;access] 
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THAWED | open Ме in “thawed” mode. 


| openfile[file;BOTH;OLD], i.e. opens file for both input and output. 


If access=NIL, value is file (full name) if file is open either for 
input or for output. Otherwise value is NIL. 


If access is INPUT, OUTPUT or BOTH, value is file if open that 
access mode, otherwise NIL. 


. Note: the value of openp is NIL if Ме is not recognized, i.e., орепр 
does not generate an error. 


орепрП returns a list of all files open for input or output, excluding 


T and the current typescript (dribble) file, if any. 


+ Тһе function zetfileinfo and setfileinfo allow the user to conveniently access such attributes of files | 


+ as dates, protection and bytesize. 


+ 
+ 
+ 
+ 
+- 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
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getfileinfo[file;attrib] 


10 
1 


12 


13 


IWRITEDATE, 


BYTESIZE 
LENGTH. 


ACCESS 


returns the current setting of the attrib attribute of file getfileinfo 


currently recognizes the following values for attrib: 


. MRITEDATE, -READDATE, CREATIONDATE | 


the date (and time) as a string that file was respectively last written, 
last read, and originally created. | 


IREADDATE, ICREATIONDATE 


the respective date іп integer — form, e.g. 
getfileinfo[file; IWRITEDATE]- idate[getfileinfo[file; WR TT EDATE]]. 


the byte size of the file. 2 
the byte position of the end-of-file.? 


the current access mode of file (e.g. INPUT, OUTPUT, BOTH, 
APPEND) or NIL if file is not open. 


getfileinfo and setfileinfo were written by Е. M. Kaplan and J. J. Vittal. 


In Interlisp-10, file may also be а JFN as returned by ра. 


Note that in Interlisp-10, it is possible that the byte size for the "opening" of a file might differ from the 
"permanent" bytesize, ie. а 7-bit text file can be opened in 36-bit mode. To obtain the "open" шы и5е 


attribute OPENBYTESIZE. 


Like geteofptr[file], but file does not have to be open. 
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The following attributes are available in Interlisp-10: + 
SIZE | the size of Ме in pages. + 
PROTECTION (ће "protection code" file as an integer. + 
DELETED T, if file is the name of a deleted file, NIL otherwise. + 

Additional attributes which are available on TOPS-20 systems are: + 
INVISIBLE T, if file has the invisible attribute, NIL otherwise. + 
ARCHIVED T, if file has been archived, NIL otherwise. + 
OFF-LINE T, if the contents of file are off-line (i.e. file has been archived and + | 

. its contents flushed), NIL otherwise. + 

setfilein fol file; attrib; value] Sets the attribute attrib of file to be value. setfileinfo returns Tifit + 

is able to change the attribute attrib, and NIL if unsuccessful (some + 
attributes cannot be changed, e.g. it doesn’t make sense to change + 
the SIZE of a Ме without writing something on it). + 
closef[ file] Closes ел“ Generates an error, FILE NOT OPEN, if file not 
open. If file is NIL, it attempts to close the primary input file if 
other than terminal. Failing that, it attempts to close the primary 
output file if other than terminal. Failing both, it returns NIL. If 
it closes any file, it returns the name of that file. If it closes either 
of the primary files, it resets that primary file to terminal. 
closef?[ file] closes file if it is open, otherwise is a no-op. Value is file. — + 
closeall[-] = all open files, except T and the current typescript file, if * 
any. Value is а list of the files closed. * 
delfile[file] deletes file if possible. Value is file if deleted, else NIL. 
renamcfilc[old;new] renames old to be new. Value is new if successful, else NIL. 

14 The whenclose package described on page 14.9 permits the user to "advise" closef to Са various openitions + 

when a Ше is closed. | + 

15 Note: the whenclose package (page 14.9) allows certain files to be "protected" from closcall, closeall[T] will + 

override this protection. + 
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MANIPULATING FILE NAMES 


Different operating systems have different conventions for naming files. However, it is desireable 
for Interlisp to be as implementation independent as possible. Therefore, all operations that need 
to reference parts of a filename, or construct new file names from existing ones, use the functions | 
filenamefield, packfilename, and unpackfilename, described below. The implementation of these 
functions obviously is dependent on the operating system they will run under, but as far as the 
programs that use them are concerned, they permit expressing operations that are implementation 
independent.lé 


Every file name is composed of a collection of fields which have different semantic interpretations. 
A field name is a literal atom which is the name of a file-name field. Interlisp assumes that NAME 
and EXTENSION are valid field names; the implementor is free to allow other fields. In 
Interlisp-10, allowable field names are: DEVICE, DIRECTORY, NAME, EXTENSION, 
VERSION, PROTECTION, ACCOUNT, and TEMPORARY. | 


 unpackfilename[filename] | returns a list of alternating fieldnames and field contents. 


Examples for Interlisp-10 on Tenex: 


. filename ипра сиспапи ша 
<LISP>MAC .COM; 3 (DIRECTORY LISP NAME MAC EXTENSION COM) 
= DSK:MYFILE | (DEVICE DSK: NAME МУЕТ! Е) 17 
_ WORK.;T | = (NAME WORK EXTENSION NIL TEMPORARY 1) 


Ша fieldname] 

| | returns the contents of the field бейин of filename, ie. 
equivalent to  listget[unpackfilename[filename]; ћејапатеј. | Бог 
example, filenamefield[<MASINTERDTEST DIRECTORY] will return 
MASINTER. 


packfilename[fieldname;; ficldcontents; ;. ..fieldname, ;fieldcontents,,] 
| lambda, nospread. "Fakes a list , Жетен fieldnames and field 
contents (atoms or strings), and returns the corresponding file name. 
For example, packfilenamc[DIRECTORY LISP NAME NET] will 
return <LISPONET. 


If the first argument to packfilename is a list, packfilename is called 
on that argument. Thus packfilename and unpackfilename operate 
as inverses. 


16 р particular, the Interlisp-10 implementation recognizes file names in both Tenex and TOPS-20 format, and builds 


new names as appropriate. 


П шт Interlisp-10, unpackfilenamc[DSK : ЕООЈ returns (DEVICE DSK: NAME FOO), ie. the : is left in. This is so 
(DEVICE NIL:) may be distinguished from (DEVICE NIL). 
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Comments: 
(1) Ifsame field name is given twice, the first occurrence is used. 


(2) packfilename recognizes the atom BODY as a fieldname meaning effectively splice into Ше 
argument list at that point all of the field names and contents specified in the operand to 
BODY. 


For example, to. take a file name and change a particular field, e.g. DIRECTORY, perform 
(PACKFILENAME 'DIRECTORY newdirectory BODY file). Alternatively, to provide a default for a 
field, e.g. the extension, perform ( PACKFILENAME 'BODY file 'EXTENSION Е This will 
use default as the extension unless one is already specified in file. 18 


ADDRESSABLE FILES 


For most applications, files are read starting at their beginning and proceeding sequentially, i.e., the 
next character read is the one immediately following the last character read. Similarly, files are 
written sequentially. A program need not be aware of the fact that there is a file pointer associated 
with each file that points to the location where the next character is to be read from or written to, 
and that this file pointer is automatically advanced after each input or output operation. This 
section describes a function which can be used to reposition the file pointer on those files that can 
be randomly accessed, thereby allowing a program to treat a file as a large block of auxiliary 
storage.l? For example, one application might involve writing an expression at the beginning of the 
file, and then reading an expression from a specified point in its middle. 


A file used in this fashion is much like an array in that it has a certain number of addressable 
locations that characters can be put into or taken from. However, unlike arrays, files can be 
enlarged. For example, if the file pointer is positioned at the end of a file and anything is written, 


the file "grows." It is also possible to position the file pointer beyond the end of file and then to- 


write.^! In this case, the file is enlarged, and a "hole" is created, which can later be written into. 
Note that this enlargement only takes place at the end of a file; it is not possible to make more 
room in the middle of a file. In other words, if expression A begins at positon 1000, and 
expression B at 1100, and the program attempts to overwrite A with expression C, which is 200 
characters long, part of B will be clobbered. 


ве ери еј returns current value of Ме pointer for Ме, i.e., the byte address at | 


which the next input/output operation will commence. getfileptr 
compiles open. 


18 Note that a null field is a field that Aas been specified, e.g. if Ше-- F00;1 in the above example, the default extension 
will be used, but if file=FOO.;1, it will not, because a null extension has been specified. 

19 The pmap facility (Section 21) provides for paged access to binary files in Interlisp-10. 

20 This particular example requires the file be open for both input and output. This can be achieved via the function 
iofile. However, random file input or output can be performed on files that have been opened in the usual way by 
infile or outfile. 

21 


If the program attempts to read beyond the end of file, an END OF FILE error occurs. 
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setfileptr[file;adr] . sets file pointer for file to adr,22 Value is adr. adr=-1 corresponds 


— 


to the end of file.23 


geteofptr[file] Value is byte address of end of file, i.e., the number of bytes in the 


file. Equivalent to performing setfileptr[file;-1] and returning 
getfileptr[file] except does not change the current file pointer. 


+ randaccessp[file | value is file if file is randomly accessible, NIL otherwise, e.g. T, 


+ 


+ 5 


TRA +++ + + 


LPT:, NIL:, etc. are examples of files not randomly accessable. - 
file must be open or an error is generated, FILE NOT OPEN. 


filepos[pattern;filename;filestart; fileend;skip;tail;casearray] 


2 


23 


Searches file for pattern a la strpos (Section 10). Search begins at 
filestart (or if filestart - МІ, the current position of the file 
pointer), and goes to fileend (or if fileend=NIL, to the end of file). 
Value is address of start of match, or NIL if not found. skip can be 
used to specify a character which matches any character in the Ме. 
If tail is T, and the search is successful, the value is the address of 
the first character after the sequence of characters corresponding to 
pattern, instead of the starting address of the sequence. In either 
case, the file is left so that the next i/o operation begins at the 
address returned as the value of filepos. 


casearray, if supplied, should be an array of 128 integers (as created | 
by array[128;128]) Each character in the file is mapped "thru" 
casearray in the sense that character code i is turned into 


elt[casearray;i--1] before matching. саѕеаггау = NIL means по 
transformation will be performed. | P. 


For example, to search without regard to upper and lower case differences, casearray would be an 
аттау where elt[cascarray;i]-i, except for lower case characters whose corresponding elements 
would be the upper case characters. To search for a delimited atom, one could use " atom " as the 
pattern, and specify a casearray in which all of the break and separator characters mapped into a 
space. | | 


The address of a character (byte) is the number of characters (bytes) that precede it in the file, i.e., 0 is the address 
of the beginning of the file. However, the user should be careful about computing the space needed for an 
expression, since end-of-line in Intetlisp-10 is represented as two characters in a file, but nchars only counts it as one. 


Note: in Interlisp-10, if a file is opened for output only, either by оше, or openfile[file; OUTPUT], TENEX assumes 
that one intends to write a new or different file, even if a version number was spccified and the corresponding file 
already exists. Thus, setfileptr[file;-1] will set the file pointer to 0. If a file is opened for both reading and writing, 
to read. Thus, the initial file pointer is the beginning of the file, but setfilepti[file;-1] will set it to the end of the file. 
Note that onc can also open а Ше for appending by openfile[filc:APPEND]. In this case, the file pointer right after 
opening is sct to the end of the existing file. Thus, a write will automatically add material at the end of the file, and 
an sctfileptr is unnecessary. | 
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seprcase[clispflg] | returns а cascarray suitable for use by filepos (or ffilepos described 
| bclow) in which all of the break/separators of filerdtbl are mapped 
into the same character. If clispflg is non-NIL, then all clisp 


characters will be mapped into this character as well. Useful for | 
finding a delimited atom in a file. For example, if pattern is 


" FOO ", and seprcasc[T] is used for casearray, then filepos will 
find "(FOO*". 


For cies calling for extensive file searches, the function ffilepos will generally be 10 to 50 
times faster than filepos. 


ffilepos[pattern;filename;filestart;fileend;skip; tail; :casearray] 
Like filepos, except much faster in most applications. ffilepos 5 is an 
implementation of the Boyer-Moore fast string scarching algorithm 


[Boy]. This algorithm preprocesses the string being searched for. 


+ + + + + + + 


and then scans through the file in steps usually equal to the length | 


of the string. Thus, ffilepos speeds up roughly in proportion to the 
length of the string, e.g., a string of length 10 will be found twice | 


as fast as a string of length 5 in the same position. 


Because of certain fixed overheads, it is generally better to use - 
 filepos for searches through fewer than 100 characters of the file. | 


For longer searches, ffilepos will generally be marginally faster for 
short strings (length 3 or less) and тышау faster for longer 
strings. 


copybytes[srcfil;dstfil;start;end] copies bytes, ie. characters, from srcfil to dstfil starting from 
position start and up to but not including position end. Both srcfil 
and dstfil must be open. Value is T. If end=NIL, start is 
interpreted as the number of bytes to copy (starting at the current 
position). If start is also NIL, bytes are copied until end-of-file is 
reached. 


CLOSING AND REOPENING FILES - THE WHENCLOSE PACKAGE” 


This package permits the user to associate with open files certain operations that govern how and 
when the file will be closed, and how the file's status will be restored when a sysout is started up. 
The user can specify that certain functions will be executed before closef closes the file and/or after 
closcf closes the file. The user can make a particular file be invisible to closcall, so that it will 


remain open across user invocations of closcall. Finally, the user can associate a status-saving | 


function with a file which will be called before sysout and which can specify what to do when a 
sysout is restarted. 


The basic user entry to these capabilities is the function whenclose. 


24 The whenclose package was written by R. M. Kaplan and Г. M. Masinter. 
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whenclose[file:prop } ;val);.. apr ЧАЈ | | 

TEC lambda no- spread. The first argument of whenclose must specify 
the name of an open file other than T (NIL defaults to the non-T 
primary input file or non-T primary output Ме). Тһе remaining 
arguments specify properties to be associated with the full name of 
file. whenclose returns the full name of file as its value. The 
property names are drawn from the following set: 


BEFORE | val is a function that closef will apply to the full name of file just 
A before it is closed. This might be used, for example, to copy 
information about the file from an in-core data structure to the file 

just before it is closed. 


AFTER val is a function that closef will apply to the full name of file just 
after it is closed. This capability permits in-core data structures that 
know about the file to be cleaned up when the file is closed.” 


For example, the pmap package (Section 21) keeps track of the 
pages from an open file that have been page-mapped into in-core 
. buffers. Those buffers must be cleared when a file is closed, or the 
` file's JFN will not get released. Thus, when a file is first "mapped" 
in, whenclose[file;AF TER;PMAPAFTERCLOSE] is performed, where 
pmapafterclose is a function which clears the buffer of any pages 
into which its argument is mapped. 


. STATUS This property provides a way of restoring the status of files when a 
| . зузош is resumed. val is a function that will be applied to the full 
name of file just before a sysout. val is expected to return a list, 
car of which is a function which will be apply’d to the cdr when 
the sysout is started up and which will restore the status of file. If 
the value of the apply is NIL, it is assumed the file could not be 
successfully restored, a warning message is printed, and then any 
AFTER functions associated with the Ше: аге ехесщед. 


CLOSEALL . val is either YES or NO and determines whether Ме will фе closed 
| by closeall (YES) or whether closcall will ignore it (мо).27 


ЕОЕ val is a function that will be applied to the full name of Ме when. 
an end-of-file error оссигѕ.28 The function can examine the context 
of the error, and can decide whether to close the file, retfrom some 


+++ ++ ++++++++ +++++++ +++ ++++ ++ ++ + + + 


F 25 BEFORE and AFTER also differ in their the behaviour with respect to sysout: The AFTER function will also be 
+ executed when а sysout is started up, unless a STATUS function is also associated with the file and it causes the file 
+ to be successfully restored. 
E 26 permstatus (Section 24) produces an expression for re-opening a file after sysout and restoring as many of its 
+ attributes as possible. 

| + v closeall uses closef, so that any AFTER functions will be executed if the file is in fact closed. 
+ 


25 and the errortypelst entty for that error, if any, returns NIL. 
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function, or perform some other computation. If the function 
supplied returns normally (i.c. does not retfrom some function), the 
normal error machinery will be invoked (but file will not be 
automatically closed if the EOF function did not close it), 


Note that multiple AFTER and BEFORE functions may be associated with a file; they are executed 
_ jn sequence with the most recently associated function executed first. However, a second STATUS 
specification will. supercede an earlier one. The CLOSEALL and EOF values will also override 
earlier values, so only the last value specified will have an effect. Files are initialized with 
CLOSEALL - YES, EOF - CLOSEF. 


14.2 INPUT FUNCTIONS 


++++ 


+ + + + + 


Most of the functions described below have an (optional) argument file which specifies the пате of Е 


the file on which the operation is to take place, апа an (optional) argument rdtbl, which specifies 
the readtable to be used for input. If file is NIL, the primary input file will be used. If the file 
argument is a string, input will be taken from that string (and the string pointer reset accordingly). 
If rdtbl is NIL, the primary readtable will be used. readtables are described on page 14.23. 


Note: in all Interlisp-10 symbolic files, end-of-line is indicated by the characters carriage-return and 
line-feed in that order. Accordingly, on input from files, Interlisp-10 will skip all line-feeds which 
immediately follow carriage-returns. On input from terminal, Interlisp will echo а line-feed 
whenever a carriage-return is input. | 


For all input functions except readc апа peekc, when reading from the terminal, control-A erases 
the last character typed in, echoing a \ and the erased character. Control-A will not backup 
beyond the last carriage-return. Typing control-O causes Interlisp fo print ЖЖ and clear the 
input buffer, Le, erase the entire line back to the last carriage-return.? When reading from а file, 
and an end of file is encountered, all input functions close the file and generate an error, END OF 
FILE. 


read[file;rdtbl; flg] Reads one S-expression from file. Atoms are delimited by the 
break and separator characters as defined in rdtbl. To input an 
atom which contains a break or separator character, precede the 
character by the escape character 9, e.g., AB%(C, is the atom 
AB(C, %% is the atom 90, %ТА (1е., %control-A) is the atom ТА. 
For input from the terminal, an atom containing an interrupt 
characier can be input by typing instead the corresponding 
alphabetic character preceded by control-V, e.g., ТУС for control-C. 


Strings are delimited by double quotes. То input a string 
containing a double quote or a Фо, precede it by 9, e.g., "ABZ"C" 
is the string AB"C. Note that % can always be typed even if next 
character is not "special", e.g., %А%В%С is read as АВС. 


29 Note that the CHARDELETE and LINEDELETE characters can be redefined or disabled via setsyntax, see page 14.25. 


30 unless the whenclose package has been used to alter this behavior (see page 14.9). 
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If an atom is interpretable as a number, read will create a number, 
ер. 1E3 reads as a floating point number, 103 as a literal atom, 
1.0 as a number, 1,0 as a literal atom, etc. Note that an integer can 
be input in octal by terminating it with а Q, e.g., 170 and 15 read. 


іп as the same integer. Тһе setting of radix, page 14.34, 


determines how integers are printed, i.e., with or without Q's. 


When reading from the terminal, all input is. line-buffered to enable the action of control-Q. A. 


Thus no characters are actually seen by the program until. a carriage-return is typed? 32 However, | 
for reading by read, when a matching right parenthesis is encountered, the effect is the same аз | 


though a carriage-return were typed, i.e, the characters are transmitted 33 To indicate this, Interlisp | 
also prints a алш return line- Seed on the terminal. | 


ratom[file;rdtbi] 


rstring[file;rdtbl] | 


31. 


32 


33 


34 | 


 ratom. Note however that ratom takes no special action for 


flg=T suppresses the carriage-return normally typed by read 
following a matching right parenthesis. (However, the characters 
are still given to read - ie. the user does not have to type the 
carriage-return himself.) | 


When reading a list, typing control-W erases the last expression | 


read, echoing a ХХ and the erased expression, e.g., (NOW IS THE .. 


ТІМЕТМ NN TIME) returns (NOW IS THE) Control-W can be 
used repeatedly, and can also back up and erase expressions. on 
previous lines.?4 


Reads in one atom from file. Separation of atoms is defined by | 
rdtbl. % is also an escape character for ratom, and the remarks 
concerning control-A, control-Q, control-V, and line-buffering also 


apply. 


If the characters comprising the atom would normally be _ 


interpreted as a number by read, that number is also returned by 


" 


whether or not it is а break - character, ie. ratom never makes a 
string. 


Reads in one string from file, terminated by next break or separator 


Unless оГ has been performed (page 14.33). 


МСН the line buffering is terminated by the character with terminal syntax class EOL (see page 14. 30), which in 


most cases will be carriage-return. 


The line buffer is also transmitted to read whenever an IMMEDIATE read-macro character is typed (see page 14.27). 


However, since control-W is implemented as an IMMEDIATE read-macro character, (sce page 14.27), once it is 
typed, characters typed before it cannot be deleted by control-A ог control-Q, since they will already have passed 


through the line buffer. 
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character.?? Control-A, control-Q, control-V, and % һауе the same 
effect as with ratom. 


Note that the break or separator character that terminates a call to ratom or rstring is not read 
by that call, but remains in the buffer to become the fi rst character seen by the next reading 
function that is called. 


ratoms[a;file;rdtbl] Calls ratom repeatedly until the atom a is read. Returns а list of | 


atoms read, not including а а. 


setsepr[Ist;flg;rdtbi] +” Set separator characters for sd ine is NIL. 


setbrk[Ist;flg;rdtbl] Set break characters for rdtbl. Value is NIL. 


For both setsepr and setbrk, Ist is a list of character codes,?  flg determines the action of 
setsepr/setbrk as follows: | 


NIL clear out indicated readtable and reset break/separator characters to be those in Ist. 
0 clear out only those characters in Ist - i.e., this provides an unsetsepr and unsetbrk. 
1 add characters in Ist. 


Characters specified by sctbrk will delimit atoms, and be returned as separate atoms themselves by 


ratom. Characters specified by setsepr will serve only to delimit atoms, and are otherwise ignored. 


For example, if $ was a break character and * a separator character, the input stream 
ABC**DEF$GH*$$ would be read by 6 calls to ratom returning respectively ABC, DEF, $, GH, 
$ 1 $ • 


The elements of Ist may also be characters, e.g., setbrk[(. ,)] has the same effect in Interlisp-10 as 
sctbrk[((46 44) Note however that the "characters" 1,2,..,9 will be interpreted as character codes 
because they are numbers. 


Note: (, ), [, ]; and " are normally break characters, i.e., will be returned as separate atoms when 


read by ratom. If any of these break characters are disabled by an appropriate setbrk (or бу 


making it be a separator character), its special поп Гог read will not be restored by simply 
making it be a break character again with setbrk.3’ For more е details, see discussion in section on 
rcadtables, page 14.23-26. 


35 Note that if the next character is a break or separator, rstring will return the null string, "". This is a common 
source of program bugs. 

36 If lst=T, Ше break/separator characters are reset to be those in the system's readtable for terminals, regardless of 
value of flg, i.e., sctbrk[T] is equivalent to setbrk[getbrk[T ]]. If rdtbl is T, then the characters are resct to those іп the 
original system table. 

37 


However, making these characters be break characters when they already are will have no effect. 
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Note that the action of % is not affected by setsepr or setbrk. То defeat the action of % use 
escape], as described below. | 


гебер га Ф 
getbrk[rdtbl] 


escapefflg] | 


ratest[x] 


readc[file] 


peekc[file;rdtbl] 
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Value is a list of separator character codes. 
Value is a list of break character codes. 


If flg=NIL, makes % act like every other character for input. 
Normal setting is escape[T]. The value of escape is the previous 
setting. 


If x = T, ratest returns T if a separator was encountered 
immediately prior to the last atom read by ratom, NIL otherwise. 


If x = NIL, ratest returns T if last atom read by ratom or read 


= was a break character, NIL otherwise. 


If x = 1, ratest returns T if last atom read (by read or ratom) 
contained а % (as an escape character, e.g., %[ ог ZA%B%C), NIL 
otherwise. | 


Reads the next character, including 9, ", etc, i.e., is not affected by 


break, separator, or escape character. Value is the character. 


Action of readc is subject to line-buffering, ie. readc will not 
return a value until the line has been terminated even if a character 
has been typed. Thus, control-A, control-Q, and control-V will 
have their usual effect. If control[T] has Әсеп executed (page 
14.33), defeating line-buffering, readc will return a value as soon as 
а character is typed. Іп addition, if control-A, control-Q, or 
control-V are typed, readc will return them as values. 


Value is the next character, but does not actually read it, i.e., 
remove it from the buffer. If rdtbl=NIL, peckc is not subject to 
linc-buffering,? i.e., it returns a value as soon as a character has 
been typed. Otherwise, peekc waits until the line has been 
terminated before returning its value. This means that control-A, 
control-Q, and control-V will be able to perform their usual editing 
functions. 


If reading from the terminal, the character is echoed as soon as peekc reads it, even though it is then "put back" 


into the system buffer, where a subsequent <del> (or <control-Z > оп TOPS-20) before the character is read сап 


clear it. 


rdtbl is used to determine the escape character, parentheses characters, etc., while the line is being buffered. 
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Value is last character read from file. 


Note: read, ratom, ratoms, peekc, readc all wait for input if there is none. The only way to test 


whether or not there is input is to use геадр. 


readp[file;flg] 


waitforinput[file] 


readline[rdtbl;-;-] 


40 


41 


42 


43 


Value is T if there is anything in the input buffer of file, NIL 


 otherwise.? Note that because of line-buffering, readp may return 


T, indicating there is input in the buffer, but read may still have to 
wait. 


waits until input is available from file or from the terminal, i.e. 
from Т. waitforinput is functionally: equivalent (0 
(until (OR (READP T) (READP FILE)) do NTC): except 
that it does not use up machine cycles while waiting.*! Value is the 
device for which input is now available, ie. file or T. 


file can also be an integer, in which case waitforinput will wait until 
there is input available from the terminal, or until file milliseconds 


have elapsed. Value is T if Шри: is now available, NIL in the case - 


that waitforinput timed out. 


reads a line from the terminal, returning it as a list. If readp[ T] is 


NIL, readline returns NIL. Otherwise it reads expressions, using 


read, *? until it encounters either: 


(1) acarriage-return (typed by the user) that is not preceded by 
any spaces, e.g., 
A B C2 
and readline returns (A В C) 


(2) а list terminating in a "p in which case the list is included 
in the value of readline, e.g, A B (C D] and readline 
returns (A B (C D)). 


(3) an unmatched right parentheses or right square bracket, 
which is not included in the value of readline, e.g., | 


Frequently. the input buffer will contain a single EOL character left over from a previous input. For most 
applications, this situation wants to be treated as though the buffer were empty, and so readp returns NIL. However, 
if g=T, readp will also return T in this case, i.e., will return T if there is any character in the input buffer. 


waitforinput operates by dismissing, checking for available input, and then, if there is none, dismissing again, each 
{те for an increasingly larger interval. The initial interval is the dismissinit milliseconds (initially 500), and the 
interval grows by 1/16 for each dismissal, up to a maximum of dismissmax milliscconds (initially 10,000). 


Actually, readline performs (APPLY* LISPXREADFN Т), as described in Section 22. lispxreadfn is initially READ. 


Note that carriage-return, i.e, the EOL character, can be redefined with setsyntax, page 14.25. readline actually 
checks for the EOL character, whatever that may be. The same is true for right parenthesis and right bracket. 
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A B C] 
and readline returns (A B C). 


In the case that c one Or more spaces 506 а carriage-return, ог а list is terminated ith a. 
Е readline will type "..." and continue reading on the next line, 44 е, g., 


and readline returns (A B C (D E F) (X Y Z)). 


skread[file;rereadstring]^? _ ва skip read function. It moves the file pointer for file ahead as if 

e : | one call to read had been performed, without paying the storage 
and compute cost to really read in the structure. rereadstring is for 
the case where the user has already performed some readc’s and 
ratom’s before deciding to skip this expression.*® In this case, 
rereadstring should be the material already read (as a string), and 
skread operates as though it had seen that material first, thus 
getting its paren-count, double-quote count, etc. set up properly. 


The value of skread is %) if the first thing encountered was a 
closing paren; %] if the read terminated on an unbalanced %], i.e., 
one which also would have closed any extant open left parens; 
otherwise the value of skread is NIL. 


44 If the user then types another carriage-return, the line will terminate, e.g., 
A B C 9 
ыз 
and readline returns (A В С). 
45 skread was written by J. W. Goodwin. It always uses filerdtbl for its readtable. 
46 


skread may have difficulties if unusual read-macros have been added to filerdtbl. skread will not recognize read- 
macro characters in rereadstring, nor SPLICE or INFIX read macros. This is only a problem if the read-macros are 
defined to parse subsequent input in the file which docs not follow the normal parenthesis and string-quote 
conventions іп filerdtbl. | | 


+ жж 
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14.3 OUTPUT FUNCTIONS 


Most of the functions described below have an (optional) argument file which specifies the name of 


the file on which the operation is to take place. If file is NIL, the primary output file will be 
used. Some of the functions have an (optional) argument rdtbl, which specifies the readtable to be 
used for output. If rdtbl is NIL, the primary readtable will be used. 


Note: in all Interlisp-10 symbolic files, end-of-line is indicated by the characters carriage-return and 


line-feed in that order. Unless otherwise stated, carriage-return рр in the description of ап 
output Junction means carriage-return and line-feed. | 


prin х; Меј prints х оп Ше. 


"7 


prin2[x;file;rdtbl] prints x on file with %’s and "5 inserted where required for it to 
read back in properly by read, using rdtbl. 


Both prinl and prin2 print lists as well as atoms and strings; prinl is usually used only for 
explicitly printing formatting characters, e.g., (PRIN1 (QUOTE %[ )) might be used to print а left 
square bracket (the % would not be printed by prinl). prin2 is used for printing S-expressions 
which can then be read back into Interlisp with read 1.е., break and separator characters in atoms 
will be preceded by %’ 5, €.g., the atom "О" is printed as %(%) by prin2. If radix = 8, prin2 prints a 
О after integers but prin] does not (but both print the integer in оска1).4? 


print[x; file;rdtb]] Prints the S- "expression x х using prin in2: followed i by. a carriage-return 
line-feed. Its value is x. 


For all printing functions, pointers other than lists, strings, atoms, or numbers, are ore as 
ЖМ, where N is the octal representation of the address of the pointer (regardless of radix). 
Note that this will not read back in correctly, ie, it will read in as the atom "XN", 


spaces[n; file] Prints n spaces; its value is NIL. 
terpri[file] Prints a carriage-return; its value is М11.49 
9c | 
tab[pos;minspaces; file] performs appropriate number of spaces to move to position pos. 
47 prin3 and prin4 аге the same as prin] and prin2 respectively, except that they do not increment the position counter _ 
nor perform any linelength checks. They are useful primarily for printing control characters. 
48 unless defprint (page 14.22) has been used to specify a printing function for this particular data type. 
49 


Note: a sequence of print, prin2, spaces, and terpri expressions can often be more convenicntly coded with a single 
printout statement (Section 23), 
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с Showprint[;x ;file;rdtbl] 
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printbells[] 


+++ 


dobe[] 
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PRINTLEVEL 


The print functions print, 


printlevel[carn;cdrn] 


+ + + + +++ 


Section 14: Input/Output 


 minspaces indicates how many spaces must be printed (if NIL, 1 is 
used). Thus, if position + minspaces is greater than pos, tab does 


а terpri and then spaces[pos]. Note: if minspaces is Т, and position 
is greater than pos, tab does nothing. 


like prin2 except if sysprettyflg=T, prettyprints x instead. Value is 
X. | 


— 


like print except if sysprettyflg — T, prettyprints. X ае оный 
by а carriage-return line-feed. Value 15 Х. | 


showprint and showprin2 are used by the programmer’s iu (Secton 22) for printing the values 
of expressions and for printing the history list, by various commands of the break package (Section 
15), e.g. ?- and BT commands, and various other system packages. The idea is that by simply 
зец пе or binding sysprettyflg to T (initially NIL), the user instructs the system when interacting 
with the user to prettyprint s-expressions (see page 14.43) instead of printing them. | | 


used by DWIM (Section 17) to print a sequence of bells to alert the 


user to stop typing. Can be advised or redefined for special 


applications, e.g. to flash the screen on a display terminal. 


dismiss until output buffer is empty, i.e. until all of the characters 


that have been printed by Interlisp functions have actually been 
printed on the users terminal. For example, it is important 10. 
perform a dobe afler printing an error message before clearing the 
input buffers to make sure that the user has actually seen the error 
message. 


prinl, and prin2 are all affected by a level parameter set by: 


Sets car print level to carn, cdr printlevel to cdrn. Value is dotted 
pair of old settings. Initial value is (1000 . -1). | 


In order that printlevel can be used with resetform or resetsave, 
printicvel[x} where x is a dotted pair is equivalent to 
printlevcl[car[x ;cdr[x]]. 


printlevel[n;NIL] changes car printlevel without affecting cdr 
printlevel. printlevel[NIL;n] changes cdr printlevel with affecting 
car printlevel. printlevcel[] gives current setting without changing 
cither. | | 
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The car printlevel controls the number of unpaired left parentheses which will be printed. Below 
that level, all lists will be printed as & For example, ifx = (A (В С (0 (Е Ғ) 6) Н) К). 
Then if carn = 2, print[x] would print 

(A (B C & H) К), and if cam = 3, (A (B C (0 & 6) H) K), and if carn = 0, just &. 


If car printlevel is negative, the action is similar except that a carriage-return is inserted between all 
occurrences of right parenthesis immediately followed by a left parenthesis. 


The cdr printlevel affects the number of elements of a list that will be printed before the printing 
is terminated with --. For example, if cdrn=2, (A B C D E) will print as (A B --). The 
decision to terminate printing of a tail of a list is also affected by the depth of printing in the car 
direction: whenever the sum of the number of cdrs at the current level and number of cars, i.e. 
unmatched left parentheses, is greater than the cdr printlevel, printing stops. This gives a 
"triangular" effect in that less is printed the farther one goes in either car or cdr direction. For 
example, if cdr printlevel=2, then (A (8 С (0 (Е Е) 6) Н) K L) will print as (А x ==) 
--) апа if cdr printlevel=3, as (А (B C --) К --). 


If cdr printlevel is negative, then the action of cdr printlevel is disabled, i.e. same as though cdr 
printlevel were infinite. 


The printlevel setting can be changed dynamically, even while Interlisp is printing, by typi ng 


control-P followed by a number, 1.е., a string of digits, оне! Бу a period or exclamation point. 
The car printlevel will immediately be set to this питрег. If the print routine is currently deeper 
than the new level, all unfinished lists above that level will be terminated by "--)". Thus, if a 
circular or long list of atoms, is being printed out, typing control-PO. will cause the list to be 
terminated. 


If the string of digits following a control-P is terminated by a comma, another number may be 


typed terminated by a period or exclamation point. The car printlevel will then be set to the first 
number, the cdr printlevel to the second number. | 


In either case, if a period is used to terminate the printlevel setting, the printlevel will be returned 
to its previous setting afler the current printout has finished. If an exclamation point is used, the 
change is permànent and the printlevel is not restored (until it is changed again). 


Note: normally printlevel only affects terminal output. Output to all other files acts as though 
level is infinite. However, if plvlfileflg is T (initially NIL), then printlevel will affect output to files. 


50 As soon as control-P is typed, Interlisp clears and saves the input buffer, clears the output buffer, rings the bell 
indicating it has seen the control-P, and then waits for input which is terminated by any non-nuniber. The input 
buffer is then restored and the program continucs. If the input was terminated by other than a period or an 
exclamation point, it is ignored and printing will continue, except that characters cleared from the output buffer. will 
have been lost. | 

51 


Another way of "turning off" output is to type control-O, which simply clears the output buffer, thereby effectively 
skipping the next (up to) 64 characters. 
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PRINTING NUMBERS? 


Interlisp defines standard print-names for fixed and floating point numbers. These print-names are 
used whenever numbers are printed by the ordinary printing functions prinl, prin2, etc. The 
print-names of numbers normally can be affected іп two ways: the print-name for integers is 
sensitive to the current setting of radix, and the print-name for floating numbers is sensitive to the 
current setting of flt£mt. The facilities described in this section permit greater controls on the 
printed appearance of numbers, allowing such things as left-justification, suppression of trailing 
decimals, etc. | | 


The basic function for printing numbers under format control is printnum: 


printnum[format; number;file] prints number on file according to the format format. format is a 
list structure of one of the following two forms: 


(FIX width radix pad leftflush) 
(FLOAT width decpart exppart pad round) 


For a FIX format, number will be rounded to the nearest integer, 
and then will be printed in a field width characters long with 
radix = radix (or 10 if radix = NIL). If pad and leftflush are both 
NIL, the number will be right-justified in the field, and the padding 
characters to the left of the leading digit will be spaces. If pad is T, 
the character "0" will be used for padding. If leftflush is T, then 
the number will be left justified in the field, with trailin trailing spaces to 
fill out width асы | 


“Тһе following examples illustrate the effects of the FIX format options ne vertical bars indicate 


the field width): 


format number | | result 
(FIX 2) | 3 mE | 3| 
(FIX 2 NIL T) 7 |07| 
(ҒІХ 12 -8 Т) 14 | 000000000016 | 
(FIX 5 NIL NIL T) 2 | | |2 | 


For a FLOAT format, number will be printed as a decimal number 


52 The printnum package was designed and implemented by К. М. Kaplan. Its utility is considerably enhanced when 
used in conjunction with the printout package (Section 23), which implements a compact language for specifying 
complicated sequences of elementary printing operations, and makes fancy output formats easy to design and simple 
to program. 
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format can also be a machine dependent format-code as returned by numformatcode. See discussion on page 14.22. 
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in a field width characters wide. There will be decpart digits to the 
бор of the decimal point (decpart=NIL is equivalent to 0). If 


exppart is not 0 (or NIL), the number will be printed in exponent - 


notation, with the exponent occupying exppart characters in the 
field. exppart must allow for the character E and a sign that will 
be printed before the exponent digits. As with FIX format, 
padding on the left will be with spaces, unless pad is T. If round is 
given, it indicates the digit position at which rounding is to take 
place, counting from the leading digit of the number. 


- FLOAT format examples: 


format | . number = result 
(FLOAT 7 2) | 27.689 |] 27.69| 
(FLOAT 7 2 NIL T) 27.689 |. |0027.69| 
(FLOAT 11 2 2) | 27.689 12768.90Е-02| 
(FLOAT 7 2 NIL NIL 1) 27.689 | 30.001 
(FLOAT 7 2 NIL NIL 2) 27.689 E | 28.00] 


If number is not a number and not NIL, а NON-NUMERIC ARG- 
error will be generated. If number is NIL, the effect depends оп 
the setting of the variable nilnumprintflg. If nilnumprintflg is NIL, 


then the error will occur. If it is non-NIL, then the value of 
nilnumprintflg will be printed right-justified in the field described 


by format. This option facilitates the printing of numbers in- 


aggregates with missing values coded as NIL. 


The full print-name number will be printed if the value will not fit 
in the field specified. Then a tab is executed so that the line 


position of the file afler printnum is always the position pror: to. 


printing plus the indicated width. 


Formatted printing of numbers usually receives assistance from the operating system, provided that 
the format is specified in some sort of special code. printnum works by converting the machine- 
independent format specifications described above into machine-dependent codes the exact form of 
which may vary from implementation to implementation. This conversion process takes place on 
cach call to printnum. For efficiency purposes, if the user is going to be performing a particular 


call to printnum frequently, he may wish to separate the conversion from the actual printing, 


performing the conversion process just once and saving the result. The function numformatcode is 
available for this purposc: numformatcode takes a format, performs the conversion and returns а 
machine dependent format-code, which can be given to printnum in place of a list structure format 


as described above. In this case, printnum will not have to perform the conversion, but can simply . 


use the machine-dependent format code directly. 
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. defprint[type;fn] |». [n interiisp: -10, type is either a type name 
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 numformatcode[format]] сопуегіѕ the FIX or FLOAT format to a machine-dependent 


format- code. 


Note: in Interlisp-10, the function fltfmt (page 14.35) will accept FLOAT formats as described 
above, in addition to the bit specification required for the Tenex FLOUT JSYS. 


USER DEFINED PRINTING 


55 or type number. 
-Whenever a printing function, print, prinl, prin2, etc. encounters an 
object of the indicated type, fn is called with Ше item to be printed 
as its argument. If it returns NIL, the datum is printed as the 
system defaults, ie. for user data types, it will be printed as 
#nonnnnn. If fn wishes to specify how the datum should be 
printed, it should return a list of the form (істі. item2). Шеті 
will be printed using prinl (unless it is NIL), and then item2 
printed using prin2 with по spaces between the two items. 
(Typically, йеті will be a read macro Ох 


Note that defprint also affects internal calls to print from pack, concat, etc., i.e. any operation t that 
involves obtaining a print name oe Section 10). | | 


DUMPING UNUSUAL БАТА STRUCTURES 


‘Hori nt? is a package for printing and reading back in more general data structures that cannot 


normally be dumped and loaded easily, e.g., (possibly re-entrant or circular) structures containing 
user datatypes, arrays, hash tables, as well as list structures. Hprint will correctly print and read 
back in any structure containing any or all of the above, chasing all pointers down to the level of 
literal atoms, numbers or strings. 


Hprint operates by simulating the їр: print routine for normal list structures. When it 
encounters a user datatype (see Section 23), or an array or hash array, it prints the data contained 
therein, surrounded by special characters defined as read-macro characters (see page 14.26). 
While chasing the pointers of a structure, it also keeps a hash table of those items it encounters, 


and if any item is encountered a second time, another read-macro character is inserted before the 


54 . In Interlisp-10, numformatcode has a second argument, smashcode. If smashcode is recognized as a format-code 
data-structure, then the new format-code will be smashed into that structure instead of allocating new storage. 


numformatcode[] will simply return an uninitialized datum that can be later smashed. 


35 Тһе user can specify different action for type names ARRAYP, HARRAYP, TERMTABLEP, READTABLEP, and 


CCODEP, even though they all have the same type number. 


56 (ог Horrible PRINT. The hprint package was written by L. M. Masinter. 


57  Hprint currently cannot handle compiled code arrays, stack positions, or arbitrary unboxed numbers. 
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first occurrence,-8 and all subsequent occurrences are printed as а back reference using an | 


appropriate macro character. Thus the inverse function, hread merely calls the Interlisp read 
routine with the appropriate readtable. 


hprint[x;file;uncircular] prints x on е. If uncircular = T, hprint does no checking for any 
circulatities in x (but is still useful for dumping arbitrary structures 
of arrays, hash arrays, lists, user data types, etc., that do not contain 
circularities), which results in a large. speed and internal- ‘storage 


advantage. 
hread[file] reads an hprint-ed expression from file. | 
hcopyall[x] copies data structure x. x may contain circular pointers as well. as 


arbitrary structures. 


Note: HORRIBLEVARS and UGLYVARS (page 14.59) are two file package commands for dumping 
and reloading circular and re-entrant data structures. They provide a convenient interface to hprint 
and hread. 


14.4 READTABLES AND TERMINAL TABLES® 


The Interlisp input and (to a certain extent) output routines are table driven by readtables and 
terminal tables. Read tables are objects that specify the syntactic properties of characters for input 


(and some output) routines. Since the input routines are concerned with parsing incoming 


character sequences into objects, the readtable in use at the time determines which sequences are 
recognized as literal atoms, strings, list structures, etc. Terminal tables are objects which supply the 
input/output routines with information specifically pertaining to the file T, and are described later. 


A readtable is a datum! that contains information about the syntax class of each character, e.g., 
break character, separator character, escape character, list or string delimiter, etc. The system 
packages use three readtables: T for input/output from terminals, (the value of) filerdtbl for 
input/output from files, and (the value of) cditrdtbl, for input from terminals while in the editor. 
These three tables are initially equal but not eq. Using the functions described below, the user 
may change, reset, or copy these tables. He can also create his own readtables, and either explicitly 
pass them to input/output functions as arguments, or install them as the primary readtable, via 
setreadtable, and then not specify a rdtbl argument, i.e., use NIL. 


38 by resetting the file pointer via setfileptr. 

59 Note: hprint is intended primarily for output to disk files, since the algorithm depends on being able to reset the Ме. 
pointer. If file 15 not a disk file (and uncircular = NIL), a temporary Ше, HPRINT.SCRATCH, is opened, x is 
hprinted on it, and then that file is copied to the final output file and the temporary file is deleted. 

60 Readtables and terminal tables were designed and implemented by D. C. Lewis. 
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other arrays, and when applied to a readtable returns READTABLEP, 
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In Interlisp-10, readtables are represented by 129 word arrays. However, typename distinguishes rcadtables from. 
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In the discussion below, most functions that accept readtable arguments will also accept NIL as 


indicating the primary readtable, or T as indicating the system's readtable for terminals. Where | 
indicated, some will also accept ORIG (not the value of ORIG) as indicating the original system 
readtable. 


 READTABLE FUNCTIONS 


readtablep[rdtbi] Value is rdtbl, if rdtbl is a real readtable, otherwise NIL. 


~ getreadtable[rdtb]] If rdtbl=NIL, value is primary read table. If rdtbl— T, value is- 


system's readtable for terminals. If rdtbl is a real readtable, value is 
rdtbl. Otherwise, generates an ILLEGAL READTABLE error. 


setreadtable[rdtbl; flg] | resets primary — readtable to be  rdtbl9? Generates 
ILLEGAL READTABLE error if rdtbl is not NIL, T, or a real 
readtable. Value is previous setting of primary readtable, i.e., 
setreadtable is suitable for use with resetform (Section 5). 0 


copyreadtable[rdtbl] Е value is а сору of rdtbl. rdtbl can be a real readtable, NIL, T, ог 


ORIG, in which case value is a copy of original system readtable, 
otherwise generates an ILLEGAL READTABLE error. Note that 
. copyreadtable is the only function that creates a readtable. 


| resetreadtable[rdtbl; from] | copics (smashes) from into rdtbl. from and rdtbl can be NIL, T, Or 


a real readtable. Іп addition, from can be ORIG, meaning. use 
system's original readtable. 


SYNTAX CLASSES 


A syntax class is a group of characters which behave the same with respect to a particular 
input/output operation. There are nine basic syntax classes: LEFTPAREN, RIGHTPAREN, 
LEFTBRACKET, RIGHTBRACKET, STRINGDELIM, ESCAPE, BREAKCHAR, SEPRCHAR, and 
OTHER, each associated with a primitive syntactic property. In addition, there is an unlimited 
assortment of user-defined syntax classes (jointly referred to as read-macros but individually 
constituting unique syntax classes). For example, the characters which indicate the beginning of a 
list structure form a basic syntax class, LEFTPAREN. Characters which indicate the beginning of a 
string belong to the class STRINGDELIM. Characters that are not otherwise special belong to the 
class OTHER. | | 


Note that a "syntax class” is an abstraction: there is no object referencing a collection of characters 


and called a syntax class. Instead, a readtable provides the association between a character and its 
syntax class, and the input/output routines enforce the abstraction by using read tables to drive the 


If Пр--Т, setreadtable resets the system readtable for terminals. Note that the user can reset the other system 
readtables with setg, е.р., (SETQ FILERDTBL (GETREADTABLE) ). | 
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parsing.® 


The functions below are used to obtain and (re)set the syntax class of a character. ch can either бе 
a character code, or a character, i.e., if ch is a number, it is interpreted as a character code. For | 
example, in Interlisp-10, 1 indicates control-A, and 49 indicates the character 1. | | 


getsyntax[ch;table] Value is syntax class of ch with respect to table. table can be NIL, | 
| T, ORIG, or a real readtable or terminal table. ch is either a - 


character code, a character, or a syntax class. In the 1 last case, (ће | 


value of getsyntax is a list of the character codes in that class, ев. 
getsyntax[BREAK]= getbrk[]. | | | 


setsyntax[ch;class; table] sets syntax class of ch, a character code, or a character. table can be | 
either NIL, T, or a real readtable or terminal table. class is a . 
syntax class, or in the case of read-macro characters (page 14.26), | 
an expression of the form (type ... options... fn) The value of © 
setsyntax is the previous class of ch. | | | 25 


setsyntax will also accept class=NIL, Т, OR IG, or a real readtable | 
or terminal table, as being equivalent to getsyntax[ch;class], 1.е., 
means give ch the syntax class it has in the table indicated by class, 
e.g, setsyntax[%(;ORIG]. class can also be a character code ог 
character, which is equivalent to getsyntax[class;table], i.e., means 
give ch the syntax class of the character indicated by class, eg, | 
зевутах[{; 1. | | | | 


syntaxp[charcode;class;table] table is NIL, T, or a real readtable or terminal table. Value is T if 
charcode is a member of syntax class class, eg, 
syntaxp[40; LEFTPAREN]- T. class can also be a read macro type 
(described below), ер. MACRO, SPLICE, INFIX, or a read- . 
macro option, e.g. FIRST, IMMEDIATE, etc. E 


syntaxp compiles open when class is a quoted expression. Мое 
that syntaxp will not каср! а character as ап argument, only a 
character code. | 


FORMAT CHARACTERS 


A format character is a character which is recognized as special by read. There are six format | 
characters іп Interlisp namely |, ] С ) ", and %. The six corresponding syntax classes are: | 
LEFTBRACKET, RIGHTBRACKET, LEFTPAREN, RIGHTPAREN, STRINGDELIM, and ESCAPE. 
(Note that the class ESCAPE refers to the input escape character.) Making a character be a format 
character docs not disable the character currently filling that function, 1.с., it is perfectly acceptable 
to have both { and | function as left brackets. To disable a format character, assign it syntax class 
OTHER, c.g., setsyntax[%" ; OTHER]. 


63 Special thanks to J. Strother Moore for this lucid explanation taken from [M00]. 


14.25 


++ 


Section 14: Input/Output 


BREAKS, SEPARATORS, AND READTABLES 


Тһе syntax classes BREAKCHAR and SEPRCHAR correspond to those characters that are treated as 


break or separator characters by ratom but have no other Special function. For convenience, the 
syntax class BREAK is provided to refer to a// break characters, i.e. it is the union of LEFTPAREN, 
RIGHTPAREN, LEFTBRACKET, RIGHTBRACKET, STRINGDELIM, and ВВЕАКСНАВ 64 Thus, 


 getsyntax[BREAK;rdtbl] and gctbrk[rdtbi] are equivalent. 


Note that getsyntax КЕС! never return BREAK or SEPR as a value although 5 setsyntax and 5 satan p 
will accept them as arguments. Instead, getsyntax will return one of the six disjoint basic syntax 
classes that comprise BREAK. Іп most cases BREAK can be used interchangeably with 
BREAKCHAR. . However, note that setsyntax[%(;BREAK] is a nop (since %( is already a break 
character), but that setsyntax[%(;BREAKCHAR] means make %( be just a break character, and 


. therefore disables the LEFTPAREN function of %(. It is equivalent to setsyntax[Vo(; OTHER] followed 


by setsyntax[%(;BREAK]. If the user does disable one of the format characters, e.g., by performing 


„ setsyntax[%(; OTHER], it is not sufficient for restoring the formatting function simply to make the 


character again into a break character, ie. setsyntax[%(;BREAK] would not restore %( as 
LEF TPAR EN. | 


READ MACRO CHARACTERS 


The user can define various Бахаре as read-macro dee by specifying as a class an 


expression of the form (type fn), where type is MACRO, SPLICE, or INFIX, and fn is the name of 


a function, or a lambda expression. Whenever read encounters a read-macro character, it calls the 
associated function, giving it as arguments the input file and readtable being used for that call to 


read. The interpretation of the value returned depends on the type of read-macro: 


(1) MAC RO The result is inserted into the input as if that expression had been 
read, instead of the read-macro character. For example, " could be 
defined by: | 


[MACRO (LAMBDA(FL RDTBL) (KWOTE (READ FL ВОТВ 1.65 


(2) SPLICE | The result (which should be а list ог NIL) is nconc’ed into the 
input list, e.g., if ! is defined by 
| (SPLICE саса NIL (APPEND #00) )), and the value of 
foo is (A В С), when the user inputs ud Y ), the result will be 
(X A B C Y). 


(3 INFIX | _ The associated function is called with the list of what has been read 
(current level list only), in tconc format, as its third argument. 


64 For purely symmetrical reasons, the syntax class SEPR corresponds to all separator characters. However, since the 
only separator characters are those that also appear іп SEPRCHAR, SEPR and SEPRCHAR are equivalent. | 


65 ' is standardly defined as a read-macro character in T and editrdtbl. The actual definition checks to see if the next 
character is a separator, right paren, or right bracket, and if so returns " itself, e.g., (А ' B) is read as (А ' B). 


66 трап INFIX read-macro character is encountered лог in a list, the third argument to its associated function will be 
NIL. If the function returns NIL, the read-macro character is essentially ignored and reading continues. Otherwise, 
if the function rcturns a tconc list of onc element, that element is the valuc of the read. If it returns a (сопс list of 
more than one element, the list is the value of the read. 
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The function’s value is taken as a new tconc list which replaces the 
old one. For example, + could be defined by: 


(INFIX (LAMBDA (FL RDTBL 7) 
(RPLACA (CDR 7) 
(LIST (QUOTE IPLUS) 
(CADR Z) 0 
(READ FL RDTBL))) 


Z) ) 


The specification for a read-macro character сап be augmented to specify various options by giving Е 
. setsyntax a list of the form (type ... options ... fn), e.g., (MACRO FIRST IMMEDIATE fn), with the - 


following interpretations: 


ALWAYS "и the read-macro character is a break character, i.e. а member of | 


BREAKCHAR, and is always effective (except when preceded by the 
escape character). 


FIRST the read-macro character is not a break character, and is 
interpreted as a read-macro character only when it is the first 
"character seen after a break or separator character, e.g. ' is а 
FIRST read-macro character, so that A'B is read as A' p68 | 


ALONE | the read-macro character is not a break character, and is interpreted 
as а read-macro character only when the character would һауе been 
read as a separate atom if it were not a read-macro character, 1.е., 
when its immediate neighbors are both break ог separator 
characters, e.g.. * is an ALONE read-macro character in order to 
implement the comment pointer feature (see page 14.45). 


Note: ALWAYS is the default option for ALWAYS, FIRST, and ALONE. 


 ESCQUOTE, ESC when printed with р гіп2, {һе read-macro character will be preceded 


by the escape character. 


NOESCQUOTE, NOESC the read-macro character will be printed without an escape, e.g., ° is- 


a NOESCQUOTE character. 


ESCQUOTE is the default option for ESCQUOTE and NOESCQUOTE. 


67 Making a FIRST or ALONE read-macro character be а break character disables Ше read-macto interpretation, i.e., 


converts it to syntax class BREAKCHAR. Making an ALWAYS read-macro character be a break character is а no-op. | 


68 <control-Y > is also standardly defined as a FIRST read macro which returns the result of evaluating the next 


expression read as though it had been typed. 
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IMMEDIATE, ТММЕО - Ше read-macro character is immediately activated, 1.е., the character 
| | | is essentially seen by the line buffer, as an EOL, and the rest of the 
line is passed to the input function.9? 70 IMMEDIATE read-macro 
. characters enable the user to specify a character that will take effect 
immediately.’ For example, control-W is defined as ап 
IMMEDIATE read-macro character. | 


NONIMMEDIATE, NONIMMED character is a normal character with respect to the line buffering, 
and so will not be activated until a carriage-return or matching 
right parenthesis or bracket is seen. 


МОМІММЕРТАТЕ is the default option for IMMEDIATE and NONIMMEDIATE. 


Note that read-macro characters can be "nested". For example, if = is defined by 
(MACRO (LAMBDA (FL RDTBL) (EVAL (READ FL RDTBL)))) . and ! by 


= (SPLICE (LAMBDA (FL RDTBL) (READ FL RDTBL))), then if the value of foo is (A B C), 


and (X -Ғ00 Y) is input, (X (A B C) Y) will be returned. If (X |=200_ 9» is Input, 
(X A B C Y) will be returned. 


Note that if a read-macro's function calls read, and the read returns NIL, the function cannot 
distinguish the case where a RIGHTPAREN or RIGHTBRACKET followed the read-macro character, 
eg, (А B '), from the case where the atom NIL (or "()") actually appeared. Thus the first case 
is disallowed, ie. reading a single RIGHTPAREN or RIGHTBRACKET via a read inside of a 
read-macro function. If this occurs, the joue ud will be put back into the input buffer, and a 
READ-MACRO CONTEXT ERROR will be generated."? 


кайеке] | Г РВ turns off action of readmacros. If flg=T, turns them 
| „е E on. Value is previous setting. 


inreadmacrop|] | value is NIL if currently not under а read-macro function, otherwise 
x ! the number of unmatched left parentheses or brackets. 


setreadmacroflg[flg] — resets the "read-macro" flag, ie. the internal system flag that 
| | | informs read that it is under а read macro function, and causes it to 


69 
control-Q once the IMMEDIATE character has been typed, since they have ане passed through the linebuffer. 


70 Making а read-macro character be both ALONE and IMMEDIATE is a contradiction, since ALONE requires that the 
next character be input in order to see if it is a break or separator character. Thus, ALONE rcad-macros are always 
NONIMMEDIATE, regardless of whether or not IMMEDIATE is specified. 


1 ie. as soon as it is read, not as soon as И is typed. Characters that cause action as soon as they are typed аге 


. interrupt characters (see Section 16). 


> | 


put back into the buffer to be read (again) at the higher level. Thus, правта ап expression such as 9 В “(С 0] 
will work correctly. | 
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Note that as a result, characters typed before an IMMEDIATE read-macro character cannot be erased бу control-A ог | 


If a call to read from within a readmacro encounters an unmatched RIGHTBRACKET within a list, the bracket is also | 
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generate а READ- MACRO CONTEXT ERROR, if an unmatched p Of 5 
15 encountered: Value is previous value of the flag. | 


| setreadmacroflg is useful when debugging read-macro ner to avoid spurious READ-MACRO | 


CONTEXT error messages when typing into breaks, eg. the user can simply ри. 
(SETREADMACROFLG) on breakresetforms (see Section 15). | | es ме З 


ТЕНМІМДІ. ТА BLES | 


А readtable contains КОО information that is média independent. Бог сине the action ии Қ 
of parentheses is the same regardless of the device from which the input is being performed. А - 


terminal table is a datum”? that contains those syntax classes of characters that pertain to- terminal. E 
input/output operations only, e.g, DELETECHAR (control-A), DELETELINE (control-Q), ек. 1а · 


addition, terminal tables contain such information as how line-buffering is to be performed, how cub" 
control characters are to be shoed printed: whether OWE case Topul is to. be converted to upper EA 


case, etc. 
Using the functions below, the user may change, reset, or copy terminal tables. He can also create + 


his own terminal tables and install them as the primary terminal table via settermtable. However, 
unlike readtables, terminal tables cannot be pem as arguments to шр шр functions. | | 


TERMINAL TA BLE FUNCTIONS | 


termtablepfttbl] | te value: is чы, if цы 5а real terminal table NI L otherwise. 


gettermtable[ttbl] If abiit value is Da (ie., current) ра on If КЫ di ud 
a real terminal table, value is ЦЫ]. Otherwise, generates an 
ILLEGAL TERMINAL TABLE error. | А M 


settermtable[ttbl] resets primary terminal table to be- ttl. Value is previous ttbl. 


Generates an ILLEGAL TERMINAL. TABLE error if ttbl is not a | 


real terminal table. 


copytermtable[ttb]] value is a copy of ttbl. ttbl can be a real terminal table, NIL, or 
ORIG, in which case value is a copy of the original system terminal 3 
table. Note that copytermtable is the only function that creates a 
terminal table. 


resettermtable[ttbl;from] smashes from into ЦЫ. from and ttbl can be NIL ora real terminal | 
table. In addition, | from ( can be ORIG, шеш use Да 5 
original terminal table. — Е | | 


73 In Interlisp-10, terminal tables are represented (currently) by 16 word arrays. 
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getsyntax, sctsyntax, and syntaxp all work on terminal tables as well as readtables. When given 
NIL as a table argument, getsyntax and syntaxp use the primary readtable or primary terminal 
table depending on which table contains the indicated class argument, e.g., setsyntax[ch; BREAK] will 
refer to the primary readtable, setsyntax[ch; CHARDELETE] will refer to the primary terminal table. 
In the absence of such information, all three functions default to the primary readtable, e.g., 
setsyntax[ch1;ch2] refers to the primary read table. If given incompatible class and table 
arguments, all three functions generate errors, e.g, setsyntax[ch;BREAK;ttbl], where ttbl is a 


terminal table, generates an ILLEGAL READTABLE error, Ба. ПРАТ rdtbl] an 


ILLEGAL TERMINAL TABLE error. 


TERMINAL SYNTAX CLASSES 


_ There are currently six terminal syntax classes: CHARDELETE О DELETECHAR), LINEDELETE (or 


DELETELINE), RETYPE, CTRLV (or CNTRLV), and EOL.” These classes correspond (initially) 
to the characters control- А, control-Q,’> control-R, control-V, and carriage-return/line-feed. АП 
other characters belong to terminal syntax class NONE. The classes CHARDELETE, LINEDELETE, 
RETYPE, CTRLV, and EOL can contain at most one character. When a new character is 
assigned one of these syntax classes by setsyntax, the previous character 15 disabled, i.e., reassigned 
the syntax class NONE, and the value of setsyntax will be the code for the previous character of that 
class, if any, otherwise NIL. 


TERMINAL CONTROL FUNCTIONS 


echocontrol[char;mode;ttbl] ^ Used to indicate how control characters are to be echoed ог printed. 
| _ char is а character or character code. If mode= IGNORE, char is 
never printed. If mode=REAL, char itself will be printed. If 
mode= SIMULATE, output will be “simulated. If mode=UPARROW, 
char will be printed as t followed by the corresponding alphabetic 
character. The value of echocontrol is the previous output mode 
for char. If mode=NIL, the value is the current output mode 
without out changing it. it. 


Note that echoing information can be independently specified for control characters’ only. 


E (However, the function echomode described below can be used to disable all echoing.) Therefore, if 
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char is an alphabetic character (or code), it refers to the corresponding control character, e.g., 
echocontrol[Z ; UPARROW] makes control-Z echo as tZ. All other values of char generate ILLEGAL 
ARG errors. 


echomode[flg;ttbl] If flg- T, turns echoing for terminal table ttbl on. If flg=NIL, 
| | turns echoing off. Value is previous setting. 


On input from a terminal, the EOL character signals to the line buffering routine to pass the input back to the calling 
function. It also is used to terminate inputs to readline, page 14.15. In general, whenever the phrase carriage-return 
linefeed is used, what is meant is the character with terminal syntax class EOL. 

75 {о Interlisp-10 оп TOPS-20, the chardelete character is <del>, апа the line delete character is control-U. АП 


remarks bclow referring to control-A or control-Q should be read as referring to <del> and control-U in the 
TOPS-20 context. _ | 
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getechomode[ttb]] value is current echo mode for ttbl. | +. 


deletecontrol[type; message;ttbl] used for specifying the output protocol when a CHARDELETE or 
LINEDELETE is typed according to the following interpretations of 


type: 


LINEDELETE message is the | message | printed when 
LINEDELETE character is typed. Initially 
" Ж Ж 2 ae 


1STCHDEL message is the message printed the first time 
| CHARDELETE is typed. Initially "А. 


NTHCHDEL message is the message printed on subsequent 
CHARDELETE's (without intervening characters). 
Initially "" 


POSTCHDEL message is the message printed when input is 
. resumed following a sequence of one or more 
CHARDELETE "5. Initially "А".76 


EMPTYCHDEL message is the message printed when a 
CHARDELETE is typed and there are no 
characters in the buffer. Initially "# #2". 


ECHO | the characters deleted by CHARDELETE are 
| echoed. 

NOECHO the characters deleted by CHARDELETE are not 
echoed. 


For LINEDELETE, 1STCHDEL, NTHCHDEL, POSTCHDEL, and 
EMPTYCHDEL, the message to be printed must be less than 5 
characters. The value of deletecontrol will be the previous message 
as a string. If message = NIL, the value will be the previous message 
without changing it. For ECHO and NOECHO, the value of 
deletecontrol is the previous echo mode, ie. ECHO or NOECHO. 


message is ignored. 


Note: If the user's terminal is a scope terminal, deletecontrol and echocontrol can be used to make 

it really delete the last character by performing the following: echocontrol[ 8 ; REAL ], (8 is code for 
control-H, which is backspace) deletecontrol[NOECHO], (climinates echoing of deleted characters) | 
deletecontrol[ 18 TCHDEL ; "tH tH" 1, and deletecontrol[NTHCHDEL ; "^н tH" |. 


getdeletecontrol[type;ttbl] value is current deletecontrol mode for type in ttbl. Жасы; 


76 this setting of 1STCHDEL, NTHCHDEL, and POSTCHDEL makes it easy to determine exactly what has been 


deleted, namely all of the characters between the Vs. 


14.31 


Section 14: Input/Output 


. raise[flg;ttb1] 2 7 If flg=T, input is echoed as typed, but lowercase letters аге 
| converted to upper case. If flg=NIL, all characters are passed as 
typed. Value is previous sctting. 


getraisc[ttb]] | value is current raise mode for ttbl. 


LINE-BUFFERING AND CONTROL 


In Interlisp’s normal state, characters typed on the terminal (this section does not apply in any way 
to input from a file) are transferred to a line buffer. Characters are transmitted from, the line 
buffer to whatever іпри mardon initiated the request (i.e., read, ratom, rstring, or геайс)7® when а 
carriage-return/? is (уред.80 Until this time, the user can delete characters one at a time from the 
input buffer by typing control-A. The characters are echoed preceded by a \. Or, the user can 
delete the entire line aparer back to the last carriage- return by typing control-Q, in which case 
Interlisp echoes 4 #.8! (If no characters are in the buffer and either control-A or control-Q is 
typed, Interlisp echoes # #.)82 


Note that this line editing is not performed by read or ratom, but by Interlisp, i.e., it does not 
matter (nor is it necessarily known) which function will ultimately process the characters, only that 
they are still in the Interlisp input buffer. Note also that it is the function that is currently 
requesting input that determines whether parentheses counting is observed, e.g., if the user executes 


(PROGN (RATOM) (READ)) and types in A (B C D) he will have to type in the carriage-return 


following the right parenthesis before any action is taken, whereas if he types 
(PROGN (READ ) (READ) ) he would not. However, once a carriage-return has been typed, the 
entire line is "available" even if not all of it is processed by the function initiating the request for 
input, ie., if any characters are "left over", they will be returned immediately on the next request 
for input. For example, (PROGN (АТОМ), (READC)) followed by А В carriage-return will 
perform both operations. 


77 та Interlisp-10, both raise[] and raise[T] execute TENEX JSYS calls corresponding to ће TENEX command 
NORAISE. Conversion of lowercase characters to uppercase before echoing is also available via raise[0], which 
executes the JSYS calls corresponding to the TENEX command RAISE. The conversion is then performed at the 


TENEX level, i.e., before Interlisp-10 even sees the characters. The initial setting of raise in Interlisp-10 is determined _ 


by the terminal mode at the time the user first starts up the system. Following a sysin, the raise mode is restored to 
whatever it was prior to the corresponding sysout. 


78 peekc is an exception; it returns the character immediately when its second argument is NIL. 
19 i.e., the character with terminal syntax class EOL. 
80 As mentioned earlier, for calls from read, the characters are also transmitted whenever the parentheses count reaches 
0. In this case, if the third argument to read is NIL, Interlisp also outputs a carriage-return line-feed. The 
- characters are also transmitted whenever an IMMEDIATE read-macro character is typed. 
81 


Typing <del> (control-Z for Interlisp-10 on TOPS-20) clears the entire input buffer at the time it is typed, whereas 
the action of control-A and control-Q occur at the time they are read. < del > can thus be used to clear type-ahead. 


82 А5 described earlier, the CHARDELETE, LINEDELETE, and EOL characters can all be redefined, Therefore, 
references to control-A, control-Q, or carriage-return in the discussion actually refer to the current CHARDELE TE, 
LINEDELETE, ог EOL characters, whatever they may be. | 
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TURNING-OFF LINE-BUFFERING 


“Тһе function control is available to defeat this line-buffering. When operating with a terminal 
table in which control[T] has been performed, characters are returned to the calling function 
without line-buffering as described below. Тһе function that initiates the request for input 
determines how the line is treated: | 


1. read 

if the expression being typed is a list, the effect is the same as though control were NIL, 1.е., 
line-buffering until carriage-return or matching parentheses. If the expression being typed is not a- 
Jist, it is returned as soon as a break or separator character is encountered, e.g., (READ) followed 
by ABC space will immediately return ABC. Control-A and control-Q editing are available on those 
characters still in the buffer. Thus, if a program is performing several reads under control[ T ], and 
the user types NOW IS THE TIME followed by control-Q, he will delete only TIME since the rest 
of the line has already been transmitted to read and processed. 


2. ratom 

characters are returned as soon as a break or separator character is encountered. Before ТЯ 
control-A and control-Q may be used as with read, е.р., (КАТОМ) followed by ABCcontrol-Aspace 
will return AB. (RATOM) followed by (control-A will return ( and type ## indicating that 
control-A was attempted with nothing in the buffer, since the (is a break character and would 
therefore already have been read. 


3. readc/ реекс 


the character is returned immediately; no line editing 15 posible. In particular, (READC) OHNE. 
by control-A will read the control-A, (READE) followed by % will read the %. 


control[flg;ttbl] flg=T . eliminates Interlisp’s normal line-buffering for Ше. 
terminal table ttbl. | 
flg=NIL restores line-buffering (normal). 


The value of control is its previous setting. 


getcontrol[ttbl] value is current control mode for ЦЫ]. 


83 An exception to the above occurs when the break or separator character is a (, ", or |, since returning at this point 


would leave the line buffer in a "funny" state. Thus if control is T and (READ) is followed by 'ABC(', the ABC 
will not be rcad until a carriage-return or matching parentheses is encountered. In this case the user could control-Q 
the entire line, since all of the characters аге still in the buffer, | | 
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14.5 MISCELLANEOUS INPUT/OUTPUT CONTROL FUNCTIONS 


clearbuf[file; flg] с Clears the input buffer for file. If file is T and flg is T, contents of 
Interlisp’s line buffer and the system buffer are saved (and can be 
obtained via linbuf and sysbuf described below). 
When either control-D,control-E, control-H, control-P, or control-S 
is typed, Interlisp automatically does a clearbuf[T;T]. (For 
control-P and. control-S, Interlisp restores the buffer after the 
interaction. See Appendix 1.) 


linbufffig] | if flg=T, value is Interlisp’s line buffer (as а string) that was saved 
| at last clearbuf[T; T]. If Пр- NIL, clears this internal buffer. 


sysbuf[flg] same as linbuf for system buffer. | 


If both the system buffer and Interlisp's line buffer are empty, the internal buffers associated with 
linbuf and sysbuf are not changed by а clearbuf[T ; T]. | | 


bklinbuf[x] x is a string. bklinbuf sets Interlisp's line buffer to x. If greater 
| than 160 characters, first 160 taken. Value is x. 


bksysbuff] и x is a string. bksysbu f sets system buffer to x. The effect is the 
m same as though the user typed x x. Value is x. | 


bklinbuf, bksysbuf, linbuf, and sysbuf provide a way of "undoing" a clearbuf. Thus if the user 
wants to "peek" at various characters іп the buffer, he could perform clcarbuf[T ; T], examine the 
buffers via linbuf and sysbuf, and then put them back. The function resetbufs provides a 
convenient way vay of simply clearing the прие buffer, performing an interaction with the user, and 
then restoring the input buffer. 


nl | 
nlambda, nospread function. Clears any typeahead, evaluates form, | 


form,,..., form,, then restores the typeahead. Value is value of 
form,. Useful cful for handling unexpected (from the user's standpoint) 
interactions, e.g. disambiguating an input when the user may 
already have begun to typeahead the next input. Compiles open. | 


resctbufs[form; ;form»;...;form 


84 


radix[n] = Resets output radix®4 to |n| with sign indicator the sign of n. For 
n — example, in Interlisp-10, -9 will print as shown with the following 
radices: | | 

Currently, there is no input radix. 
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radix | printing 


10 | -9 | 
-10 68719476727 
| 1е., (2136-9) 
8 | -110 
8 3 7777777777670 


Value of radix is its last setting. radix[] gives current setting 
without changing it. Initial ки 15 10. 


Іп ено. -10, sets анар format control to formatbits (See 


TENEX JSYS manual for interpretation of formatbits). fltfmt[T] 
specifies free format (see Section 3).85 Value of fltfmt is last setting. | 


fitfmt[] returns current Бә without changing it. Initial н 15 


Т. 


Note: the т package, page 14.20, permit greater controls on the printed appearance of 
numbers, allowing such things as ef justification, suppression of trailing. decimals, еіс. 


linelength[n] 


setlinelength[n] 


Sets the dengtli of the want line for all files. Value is the former _ 


setting of the line length. Whenever printing an atom would go 
beyond the length of the line, a carriage-return is automatically 
inserted int.  linelength[] returns current setting. Initial setting is 
72. · iecit | | 


if n is NIL, interrogates operating system for the line length of the 
terminal device, and sets variable ttylinelength to this value. If n is 
not NIL, instructs operating system to set terminal line length to n, 
and then sets ttylinelength to n. Then, in either case, setlinelength 
performs (and returns as its value) linelength[ttylinelength]. 


Both aftersysoutforms and resetforms (Section 22) contain a (SETLINELENGTH) so that when the 
user first runs a sysout, or types control-D, the system obtains the latest information about the 
terminal. The various system functions that print to the terminal, e.g. pp, the cditor, etc., all 
perform linelength[ttylinclength] (rather that linelength[72]). Thus if the user has a wider terminal 
the "right" thing automatically happens 


85 


formatbits can also be a FLOAT format type, as described on page 14.20. 


14.35 


+ 
+ | 


+ + + + + 


+ + + + + 


++ теке 


+ 


+++ +++ 


Section 14: Input/Output 


| scttermchars[nextchar; bkchar: lastchar;unquotechar;-;-] 


used to set up the immediate read macros used by the editor (see | 
Section 9), as well as the <control-Y > read macro described 
earlier. nextchar corresponds to the <line-feed> edit command, 
bkchar to <control-X >, lastchar to <control-Z >, and unquotechar 
to <control-Y >. For each non-NIL argument, settermchars makes 
the corresponding control character have the indicated function. 


Normally, settermchars will complain if the character is already an interrupt character. However, if 


Settermchars is given a list as one of its arguments, it will use car even if the character is ап 
interrupt. In this case, if cadr of the list is non-NIL, settermchars will reassign the interrupt 


function to сайт. For example, if <control-X > is an interrupt, settermchars[(X W)] will make 
<control-W> have the effect <control-X > had, and make <control-X > be the nextchar 
operator. 


As part of the grecting operation, settermchars is applied to the value of editcharacters, which is 
initially (J X Z Ү).8° The user can reset editcharacters in his profile, or else explicitly call 


settermchars to specify some other characters to be used for the indicated function. 


с position[file;n] — ... Gives the column number the next character will be read from or 


++ 


printed to, ер. after а carriage-return, position=0. If n is 
non-NIL, resets position to п. | 


Note that position[file] is not the same as getfileptr[file] which gives the POOR in the file, not on 
the /ine. 


14.6 SYSIN AND SYSOUT 


| sysout[file] | | Saves the user’s private memory on file. Also saves the stacks, so. 


that if a program performs a sysout, the subsequent sysin will 

continue from that point, e.g., 

[PROGN (SYSOUT (QUOTE ЕОО)) (PRINT (QUOTE HELLO] . 

will cause HELLO to be printed after (SYSIN (QUOTE ЕОО)) The 

value of sysout is file (full name). A value of NIL indicates the 
. Sysout was unsuccessful, i.e., either disk or computer error, or user's 

directory was full. 


Sysout does not save the state of any open Ле.) 


. Whenever the Interlisp system is reassembled and/or reloaded, old sysout files are not compatible | 


with the new system. 


86 <control-J > 15 line-feed. The initial value of editcharacters for Interlisp on ТОР5-20 is(J А L У). 


However, the whenclose package, page 14.9, can be used to associate with open files certain operations to be 
performed when a sysout is started up, including reopening the file and repositioning the file pointer, 
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sysout is advised to evaluate the expressions on beforesysoutforms when executing the sysout, and - 


to evaluate the expressions on aftcrsysoutforms when coming back from a sysin, 1.е., when the 
. value being returned by sysout is a list. beforesysoutforms includes expressions | to: 


(1) set the variable sysoutdate to (DAT E), i.e. the time and date that the sysout was performed; 


(2) if file is non-NIL, to set the variable sysoutfile to (the body of) file. If file is NIL, the value _ 


of sysoutfile is used instead. Thus, after an initial sysout, the user can simply perform sysout[] to 
save the current state on ра next higher version of а ше with the same name as the previews 


sysout; 


(3) if an extension and a version number аге not specified, to use the value of s sysout.ext as the | 


extension (initially .SAV for Тепех sites and . EXE for TOPS- 20 sites.) 


(4) to perform any necessary operations ЖК with open files specified by calls to whenclose | 


(раре 14.9). 


Aftersysoutforms includes expressions to: 
(1) reset the terminal linelength appropriately (see discussion of setlinelength on previous page); 


(2) reset the terminal control characters if the systemtype has changed, i.e. from TENEX to 
TOPS-20 or vice versa. | | 


(3a) if the value of s sysoutgag is NIL Ge initial 5 and the sysout was made by the same user 


that is performing the sysin, to greet the user by printing the value of heraldstring followed by a 


greeting message. If the sysout was made by a different user, to warn the user that the user 
profiles may be different (see Section 22 on ај and User DH e.g. | 


жжжжАТТЕМТІОМ USER LEWIS: 
THIS SYSOUT IS INITIALIZED FOR USER HARTLEY. 
TO REINITIALIZE, TYPE GREET(). 


(3b) if the value of sysoutgag is a list, to evaluate the list in lieu of printing a message. This 
permits the user to print his own message. 


(3c) for all other non-NIL values of sysoutgag, no message is printed. 
(4) call setinitials to reset the initials used for time-stamping (Section 9). 


(5) perform any necessary operations associated with previously opened files specified фу calls to 
whenclose (page 14.9). 


sysin[file] restores the state of Interlisp from а sysout file.88 Value is 


88 ү Interlisp-10, file is а runnable file, 1.е., it is not necessary to start up an Interlisp and call sysin in order to restore 


the state of the user's program. Instead, the user can trcat the sysout file the same as a SAV file, іе, use the 
operating system RUN command, or simply type the file name to the operating system, and the effect will be exactly 
the same as having performed a sysin. 
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 cons[filezmakesys], where makesys is the name of the parent 
. system.® 
file. If file is not found, generates a FILE NOT FOUND error. 


89 


If sysin returns NIL, there was а problem in reading the 


Since sysin continues immediately where — left off the only way for a program to delene 
whether it is just coming back from a sysin or fom а зузош is to test the value of SYSOUL | 


For example, (COND ((LISTP (SYSOUT (QUOTE F00))) (PRINT (QUOTE HELLO) ))) will 
. cause HELLO to be printed following the sysin, but not when the sysout was кишш 


| sysoutp[file] 


К+ 


14.7 7 SYMBOLIC FILE 


· load[file; абе: printflg] 


+ 9 
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predicate for m whether file is a sysout file. Returns the 
name of the parent makesys (Section 3) if the file is a sysout file, 
NIL otherwise. | 


INPUT 


Reads successive 5- -expressions from file (with filerdtbl as readtable) 


and evaluates each as it is read, until it reads either NIL, or the | 
single atom STOP. Value is file (full name). 


If printflg = T, load prints the value of each S- -expression: otherwise 


it does not. ldflg lg affects the operation of define, defineg, rpaq, and 
града. While load is operating, dfnflg (Section 8) is rebound to 
idflg. Thus, if ldflg=NIL, and a function is redefined, a message 
is printed and the old definition saved. If ldflg=T, the old 
definition is simply overwritten. If Idflg=PROP, the function 
definitions are stored оп Ше .property lists under the property 
EXPR. If ldflg=ALLPROP, not only function definitions but also 
variables set by rpaqq and rpaq are stored on property 11515.21 


Another option 15 available for users who are loading systems for 
others to use, and wish to conserve space by suppressing during the 
load operation various user features designed to aid in development 
and debugging. If Idflg=SYSLOAD, load will (1) rebind dfnflg to 
T, (2) rebind lispxhist to NIL thereby making the load not be 
undoable and saving the cost of saving undo information (section 
22), (3) rebind addspellflg to NIL to suppress adding things to _ 
spelling lists, (4) rebind filepkgflg to NIL to prevent the FILE 
property from being saved and the file being "noticed" by the file 
package, (5) rebind buildmapflg to NIL to prevent a file map from 
being constructed, (6) when the load has completed, set to NOBIND 


+ 89 sysout only saves that portion of the user's environment which is private se Section 3.4 on Shared Interlisp). 
In Такер: -10, Ме can also be a JEN. 


except when Ше {йе has value NOBIND, in which case it is set to the indicated value regardless of dfnflg. 
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the fileCOMS and filevars?? and (7) add the file name to sysfiles 
rather than filelst. | 


Note: all functions that have Idflg as an argument, i.e. load, loadfns, loadvars, etc., perform spelling 
correction using loadoptions as a spelling list when Idflg is not a member of loadcptions. 
loadoptions is initially (NIL T PROP ALLPROP SYSLOAD). 


. load?[file;ldflg;printflg] 


loadfns[fns; file;ldflg; varsp4 
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like load except does not load file if it has already been loaded, B in 


which case its value is NIL. 


permits selective loading of function definitions. fns is a list of 
function names, a single function. name, or T, meaning all 
functions.” file can be either а. compiled or symbolic бе, i.e., апу 


file that can be loaded by load. The шери of 1аћа is ће | 


same as for load. 


vars specifies which non-DEFINEQ expression are to be loaded (1.е., 
evaluated): T means all, NIL means none, VARS is same as 
(RPAQQ RPAQ), FNS/VARS is same as (fileCOMS fileBLOCKS), and 
any other atom is the same as list[atom]. 


When vars is a ‘list, each atom on vars is compared with both car - 
and cadr of non-DEFINEQ expressions, e.g, either RPAQQ or 


FOOCOMS can be used to indicate (RPAQQ FOOCOMS --) should 
be loaded. For more complicated specification, each list on vars is 
treated as an edit pattern and matched with the entire 
non-DEFINEQ expression. In other words, а non-DEFINEQ 
expression will be loaded if either its car or cadr is eq to some 
member of vars, or it matches (using editie edit4e, Section 9) some list on 
vars, e.g., 
(FOOCOMS DECLARE: (DEFLIST & (QUOTE MACRO))) would 
cause (RPAQQ FOOCOMS --), all DECLARE:'s, and ай 
DEFLIST's which set up МАСКО 5 to be read and evaluated. 


The value of loadfns is a list of (the names of) the functions that 
were found, plus a list of those functions not found (if any) headed 
by the atom NOT-FOUND: e.g., (FOO ЕТЕ (NOT-FOUND: FUM)). 
If vars is non-NIL, the value will also include those expressions that 


ie. any variable appearing in a file package command of the form (filecom * variable) (see page 14.60), e.g. in 


(FNS * FOOFNS). FOOFNS is set to NOBIND. Note that if the user wants the value of such a variable to be 
retained, even when the file is loaded with ЈаПр = SYSLOAD, then he should replace the variable with an equivalent, 
non-atomic expression, e.g. (FNS * (PROGN FOOFNS)). 
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The test is whether the root name of file has a FILEDATES property. 
loadfus was originally written by J. W. Goodwin, and subsequently modified by W. Тенејтап. 


If a compiled definition is loaded, so are all compiler generated subfunctions. 
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were loaded, plus a list of those members of vars for which no 
corresponding expressions were found (if any), again headed by the 
atom NOT-FOUND:. | 


If file=NIL, loadfns will use whereis (page 14.67) to determine 
where the first function in fns resides, and load from that file. 
Note that the file must previously have been "noticed". (For more 
discussion, see page 14 63),% | 


loadvars[vars;file;ldflg] | .. same as loadfns[NT L.file;ldflg;vars]. | 


- 


loadfrom[file;fns;ldflg] same as loadfns[fus;file;ldflg;T]. 


As mentioned in Section 9, once the file package knows about the contents of a file, the user can 
edit functions contained in the file without explicitly loading them. Similarly, those functions 
which have not been modified do not have to be loaded in order to write out an updated version 


of the file. Files are normally noticed, i.e., their contents become known to the file package (page 


14.54), when either the symbolic or compiled versions of the file are loaded. If the file is not 
going to be loaded, the preferred way to notice it is with loadfrom. For example, if the user wants 
to update the file FOO by editing the function Ғ001 contained in it, he need only perform 


· loadfrom[F 00], editf[F 001], and makefile[FOO]. Note that the user can also load some functions at 


the same time by giving loadfrom a second argument, e.g., loadfrom[FO0; F001], but its raison 


d'etre is to inform the file package about the existence and contents of a ушш file. 


loadblock[fn;file;ldflg] calls loadfns on those functions contained. in the block declaration 
| | containing fn.” | 


loadefs[fns;file] | like loadfns except returns а list of functions and their symbolic 


+ + + + 


definitions, plus а list of those functions not found, if апу, headed 
by the atom NOT-FOUND:, e.g., | 

loadfns[((FOO ЕТЕ FUM);FOO] = ((Ғ00 (LAMBDA ...)) 
(FIE (LAMBDA ...)) (NOT-FOUND: FUM)). D 


loadcompj[file;ldflg] performs all operations on file associated with compilation, i.e. 
| evaluates all expressions under a DECLARE: EVAL@COMPILE, and | 
"notices" the function and variable names by adding them to 

nofixfnslst and nofixvarslst (see Section 23). 


96 If whereis[fn] returns NIL, and the whereis package (Section 24) has been loaded, loadfns will petform 
whereis[fn;F NS ; T], which will use the whereis data base to find the file containing fn. | 
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function which already has an in-core expr definition, and it will not load thc block name, unless it is 194 one of the 
block functions. 


97 loadblock is designed primarily for use with symbolic files, i.e., to load the exprs for a given block. It will not load а 
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Thus, if building a system composed of many files, and compilation information 15 scattered 
throughout these files, to compile one file, all that is required is to foadcomp | the others. 


loadcomp?[file:1dflg] like loadcomp, except does not load if file has already been loaded, 
in which case its value is NIL. 


FILE MAPS 


A file map is a data · structure which contains a symbolic " map’ of the contents of a file. Currently, 
this consists of the begin and end ада с 5" for each defineq expression in the file, the begin and 
end address for each function definition within the дейпед, and the begin and end address for 
each compiled function. 


makefile, prettydef, loadfns, recompile, and numerous other system functions depend heavily on 
the file map for efficient operation. For example, the file map enables loadfns to load selected 
function definitions simply by setting the file pointer to the corresponding address using setfileptr, 


and then performing a single read. Similarly, the file map is heavily used by the "remake" option 


of makefile (page 14.77): those function definitions that have been changed since the previous 
version are prettyprinted; the rest are simply copied from the old file to the new one, resulting in a 
considerable speedup. 


Whenever a file is read by load or loadfns, a file map is automatically built? and stored on the - 


property list of the root name™! of the f the file, under the property FILEMAP. Whenever a file is 
written by, makefile, a file map for the new file is also built, and stored on the FILEMAP 
property.? In addition, the file map is written on the file itself.10? Thus, in most cases, load and 
loadfns do not have to build the file map at all, since a file map will usually appear in the 
corresponding file.! 


The procedure followed whenever a system package that uses file maps accesses a file is embodied 
in the function getfilemap. getfilemap first checks the FILEMAP property to see if a file map for 


98 byte address, see getfileptr, page 14.8. 

99 The internal representation of the Ше map is not documented since it may change when the map is extended to 
include information about other than just function definitions. 

100 unless buildmapflg=NIL. buildmapflg is initially T. 

101 the file name with directory and version number stripped off. 

102 Building the map in this case essentially comes for free, since it requires only reading the current file pointer before 
and after each definition is written or copied. However, building the map does require that prettyprint know that it is 
printing a DEFINEQ expression. For this reason, the user should never print a DEFINEQ expression onto a file 
himself, but should instead always use the FNS command, page 14.56. 

103 For cosmetic reasons, the file map is written as the last expression in the file. However, the address of the file map 
in the file is (over)written into the FILECREATED expression that appears at the beginning of the file so that the file 
map can be rapidly accessed without having to scan the entire file. 

104 


unless the file was written with buildmapflg = NIL, or was written outside of Interlisp. 
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this file was previously obtained or built.!05 If there is none, getfilemap next checks the first 
expression on the file to see if it is a FILECREATED expression that also contains the address of a 
FILEMAP. ЈЕ neither are successful getfilemap. returns NI | 107 and a Ше map will be built. 


READFILE AND WRITEFILE | 


For those applications where the user simply wants to simply TT all of the s-expressions on a file, 
and not evaluate them, the function readfile is available: 


readfile[file] Е Reads successive S-expressions from file using read (with filerdtbl as 
| readtable) until the single atom STOP is read, or an end of file u 
encountered. Value is a list of these S-expressions. E 


writefile[x; file] Inverse of readfile. Writes a date expression onto file, followed by 
successive S-expressions from x, using filerdtbl as a readtable. If x 
is atomic, its value is used. If file is not open, it is opened. If file 
is a list, car[file] is used and Ше file is left opened.. Otherwise, | 
when x is finished, a STOP is printed on file and it is closed. Value 
is file. 


endfilc[file] Prints STOP on file and closes it. 


105 The full name of the file is also stored on the FILEMAP property along with its map. 
106 currently, file maps for compiled files are not written onto the files themselves. However, load and loadfns will build 
maps for a compiled file when it is loaded, and store it on the property FILEMAP. ш loadfns will obtain and | 


use the file map for a compiled file, when available. 


107 getfilemap also returns NIL, if usemapflg=NIL, initially T. usemapflg is available primarily to enable the user to 


recover in those cases where the file and its map for some reason do not agree. For example, if the user edits a 

· symbolic file that contains a map using a text editor such as TECO, inserting or deleting just one character will 
throw that map off. The functions which use file maps contain various integrity checks to enable them to detect that 
something is wrong, and to generate the error FILEMAP DOES NOT AGREE WITH CONTENTS OF file-name. In 
such cases, the user can set usemapflg to NIL, causing the map contained in the file to be ignored, and then 
reexecute the operation. A new map will then be built (unless buildmapflg is also NIL). 


18 White building the map will not help this operation, it will help in future references to this file. For example, if the 


uscr performs loadfrom|FOO] where FOO does not contain а file map, the loadfrom will be (slightly) slower than if 
FOO did contain a file map, but subsequent calls to loadfns for this version of FOO will be able to use the map that 
was built as the result of the loadfrom, since it will be stored оп FOO's FILEMAP property. 
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14.8 PRETTYPRINT 


„ prettyprint[Ist;-]!0? 110 Ist is a list of functions (if atomic, its value is used). Тһе 


definitions of the functions are printed in a pretty format on the _ 


primary output file using the primary readtable. For example, 


(FACTORIAL 
[LAMBDA (N) 
(COND — 
((ZEROP N) 
1) or | 
(T (ITIMES М (FACTORIAL (SUB1 NJ) 1H 


A more complete example is shown on page 14.47. 


Note: prettyprint will operate correctly on functions that are.broken, broken-in, advised, or have 
been compiled with their definitions saved on their property lists: it prints the original, pristine 
definition, but does not change the current state of the function. If prettyprint is given an atom 
which is not the name of a function, but has a value, it will prettyprint the value. If the function is 
not defined but is known to be on one of the files noticed by the file package, prettyprint will load 
in the definition (using loadfns) and print 11 12 Otherwise, prettyprint will perform Spelling 
correction. If all fails, prettyprint returns um NOT РВЕНЈАВЕВЈ: 


рріх] nlambda, nospread function that performs output[T], setreadtable[T], | 


linelength[ttylinelength], and then calls prettyprint: PP FOO is 
equivalent to PRETTYPRINT((FOO)); PP(FOO ЕТЕ) or 
(PP FOO FIE) is equivalent to PRETTYPRINT((FOO FIE)). 


Primary output file and primary readtable аге restored after. 


printing. 


As described earlier, when prettyprint, and hence pp, is called with the name of a function that is - 
not defined, but whose definition is on a file known to the file package, the definition is - 


automatically read in and then prettyprinted. However, if the user does not intend on editing or 
running the definition, і.е. he simply wants to see the definition, the function pf described below 
can be used to simply copy the corresponding bytes from the file to the terminal. This results in a 


savings in both space and time, since it is not necessary to allocate storage to actually read in the. 


definition, and since the function is already in prettyprint format on the file, it is not necessary to 
re-prettyprint it. 


109 The prettyprint package was written by W. Teitelman. 

H0 prettyprint has a second argument that is T when called from prettydef. In this case, whenever prettyprint starts a 
new function, it prints (on the terminal) the name of that function if more than 30 seconds (real time) have elapsed 
since the last time it printed the name of a function. 

Ml In order to save space on files, tabs are used instead of spaces for the inital spaces on each line, assuming that each | 
tab corresponds to 8 spaces. This results in a reduction of file size by about 30%. Tabs will not be used if. 
prettytabflg is sct to NIL (initially T). | 

112 


except when called from prettydef. 
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ра; from files; ло е) nlambda, nospread function. Copies the definition of fn found on 
| each of the files іп fromfiles (о tofile. If tofile=NIL, defaults to T. 
If fromfiles=NIL, defaults to whereis[fn;NIL; T]. Note that the 

typical useage of pf is to simply type PF fn. 


When printing to the terminal, pf performs several transformations on the characters in the file that —— 
comprise the definition for fn: (1) font information (page 14.49) is stripped out; (2) changechar 
(page 14.49) is also not printed; (3) since functions typically tend to be printed to a file with a 
larger linelength than when printing to a terminal, the left margin on each line, i.e. the number of 
leading spaces, is cut in half; and (4) comments are printed as described below. | ! 


COMMENT FEATURE 


A facility for annotating Interlisp functions is provided in prettyprint. Any S-expression beginning 
with ж is interpreted as a commenti? and printed in the right margin. .Example: / 


(FACTORIAL IPM | 
[LAMBDA (М) ДЕ (* COMPUTES М1) 
(COND - TIO AME 29 
((ZEROPN) | Ди (% 01-1) 
1) | 
(T (* RECURSIVE DEFINITION: 


МІ-М%Қ-11) 
(ІТІМЕ5 N (FACTORIAL (бива М1) 


These саб actually form а рагі of the function definition. Accordingly, * is defined as ап. 


NLAMBDA NOSPREAD function that returns its argument, ie. it is equivalent to quote. When 
running an interpreted function, * is entered the same as any other Interlisp function. Therefore, 
comments should only be placed where they will not harm the computation, ie, where a quoted | 
expression could |. be placed. For example, wtiting 
(ITIMES N (FACTORIAL (SUB1 N)) (* RECURSIVE DEFINITION)) in the above function 
would cause an error when ITIMES attempted to multiply М, М-1!, and RECURSIVE. The 
compiler (Section 18) will also detect places where a comment has been used for value, and print 
an appropriate error message. 


For compilation purposes, * is defined as a macro which compiles into no instructions. Thus, if 


the user compiles a function with comments, and load the compiled definition into another system, 


the extra atom and list structures storage required by the comments will be eliminated. This is the 
way the comment feature is intended to be used. For more options, see end of this section. 


Note: comments are designed mainly for documenting listings. Thus when prettyprinting to ще 
terminal, comments are suppressed and printed as the string **COMMENT**., E 


113. Actually, any expression саг of which is equal to the value of the variable commentflg is treated as a comment. 


commentflg is initially *, but the user can set it to some other value, e.g. ;, and use this to indicate comments. For 
more dctails, see page 14.48. 


The value of **comment**flg determincs the action. If **comment**flg is NIL, the comment is printed. Otherwise, 
the value of **comment**flg is printed. **comment**flg is initially set to " **COMMENT** ". The function pp* is 
provided to prettyprint functions, including their comments, to the terminal. pp* operates cxactly like pp except it | 
first sets *"^comment*^flg to NIL. The function pf plays an analagous role for pf. 
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COMMENT POINTERS 


For a well-commented collection of programs, the list structure, atom, and pname storage required - 


to represent the comments in core can be significant. If the comments already appear on a file and 
are not needed for editing, a significant savings in storage can be achieved by simply leaving the 
text of the comment on the file when the file is loaded, and instead retaining in core only a pointer 
to the comment. This feature has been implemented by defining * as а read-macro іп FILERTBL 
which, instead of reading in the entire text of the comment, constructs an expression containing [1] 
the name of the file in which the text of the comment is contained, [2] the address of the first byte 
of the comment, and [3] the number of bytes? For output purposes, * is defined as a 
prettyprintmacro (page 14.49) that prints the comments represented by such „pointers by simply 
copying the corresponding bytes from one file to another, or to the terminal.!ló Normal comments 
are processed the same as before, and can be intermixed freely with comment pointers. 


The comment pointer feature is enabled by setting normalcommentsflg to NIL. 


normalcommentsflg is initially T. Note that normalcommentsflg сап be changed as often as | 


desired, 1.е., some files can be loaded normally, and others using comment pointers: 


For convenience of editing selected comments, an edit macro, get*, is included which loads in the 
text of the corresponding comment. “ве is defined i in terms of getcomment: 


getcomment|x;-;-] If x is a comment Ке value is the comment, which it reads 
from the file. Otherwise, value is x. 


CONVERTING COMMENTS TO LOWER CASE 


This section is for users operating on terminals without lower case, e.g. model 33 teletypes, who | 


nevertheless would like their comments to be converted to lower case for more readable line-printer 
listings. Users with lower-case terminals can skip to the File Package sections (as they can type 
comments directly in lower case). 


%% If the second atom іп a comment is %%, the text of the comment is 
converted to lower case so that it looks like English instead of LISP 
(see next page). 


The output on the next page illustrates the result of a lower casing operation. Before this function - 


was prettyprinted, all comments consisted of upper case atoms, e.g., the first comment was (* XX 


INTERPRETS A SINGLE COMMAND). Note that comments are converted only when they are 


actually written to a file by prettyprint. 


115 Plus a flag to indicate whether the comment appeared at the right hand margin or centered on the page. 

116 If the user changes the value of commentflg but still wishes to use the comment pointer feature, he should make. 
sure to give the new commentflg the same read-macro definition in filerdtbl as * has, e.g. if he resets commenttlg to 
be ;, he should perform (SETSYNTAX '; '» FILERDTBL). | 

117 pp" prints the comment without reading it by simply copying the corresponding bytes to the terminal, 
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— The algorithm for conversion to lower case is the following: If the first character іп an atom is f, 

do not change the atom (but remove the 1). E the first character is %, convert the atom to lower 
casc.H? |f the агот 13 is an Interlisp word," do not change it. Otherwise, convert the atom to 
lower case. Conversion only affects the upper case alphabet, 1.е., atoms already converted to lower 
case are not changed if the comment is converted again. When converting, the first character in- 
the comment and the first character following each period are left capitalized. After conversion, 
the comment is physically modified to be the lower case text minus the 0% flag, so that conversion 
is thus only performed once (unless the user edits the comment inserting additional upper case text 
and another %% flag). 


lcaselst — | Words on Icaselst will always be converted to lower case. Icaselst is 
initialized to contain words which are Interlisp functions but also 
appear frequently in comments as English words. e.g., AND, 
EVERY, GET, GO, LAST, LENGTH, LIST, etc. Thus, in the 
example on the previous page, not was written as "МОТ, and GO as 
160 in order that they might be left in upper case. 


 ucaselst words on ucaselst (that do not appear on lcaselst) will be left in 
| upper case. ucaselst is initialized to NIL. 


abbrevist abbreylst is used to distinguish between abbreviations and words 

| {м that end in periods. Normally, words that end in periods and occur 
more than halfway to Ше right margin cause carriage-returns. - 
Furthermore, during conversion to lowercase, words ending in 
periods, except for those on abbrevlst, cause the first character in 
the next word to be capitalized. abbrevist is initialized to the upper 
and lower case forms of ETC. І.Е. and ЕС. 


138 User must type %% as % is the escape character. - 
119 minus any trailing punctuation marks. 
120 


ie, is a bound or free variable for the function containing the comment. or has a top level value, or is a defined 
function, or has a non-NIL property list. | 
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(BREAKCOM EOM: | 
[LAMBDA (BRKCOM BRKFLG) __ (2 Interprets а 
Single command.) 
(PROG (BRKZ) | 
TOP (SELECTQ 
BRKCOM | 
[+ (RETEVAL (QUOTE BREAK1)- 
| (QUOTE (ERROR]]. 
(GO | (* Evaluate BRKEXP 
| | unless already evaluated, 
print value, and exit.) 
(BREAKCOM1 BRKEXP BRKCOM NIL BRKVALUE) 


(BREAKEXIT)) TEE 
(OK | , | (* Evaluate BRKEXP, 


unless already evaluated, 
do NOT print value, 
| апа ех1ї.) 
(ВВЕАКСОМ1 ВВКЕХР BRKCOM. BRKVALUE BRKVALUE) 
(BREAKEXIT T)) | 
(tWGO | B Same as GO except 
| .. never saves evaluation . 
on history.) | 
(BREAKCOM1 BRKEXP- BRKCOM Т. BRKVALUE) 
ОТАРДЫ 4%. | 
(RETURN 


(* User will type in expression to be evaluated and 
returned as value of ВЕРА НЕ same as GO.) 


(BREAKCOM1 [SETQ BRKZ (соно 
(BRKCOMS (CAR BRKCOMS)) 
(T (LISPXREAD T] 
(QUOTE RETURN) 
NIL NIL (LIST (QUOTE RETURN) . 
BRKZ )) 
(BREAKEXIT) ) | 
(EVAL (* ТІ ВВКЕХР but 
| do not exit from BREAK.) 
(BREAKCOM1 BRKEXP BRKCOM) | 
(COND 
(BRKFLG (BREAK2) 
__(РЕТМТ BRKFN T) _ 
(PRIN1 (QUOTE " EVALUATED 
") 
T))) | | 
(ФЕТО !МАШЈЕ (CAR BRKVALUE)) 
(* For user's benefit.) 
) ; 
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SPECIAL PRETTYPRINT CONTROLS 


# rpars | 


linelength[n] 


firstcol 


 prettylcom 


# carefulcolumns 


` widepaper[flg] 


commentflg 


121 


122 


· determines the position of the right margin for prettyprint. 


controls the number of right parentheses necessary for square 
bracketing to occur. If #rpars=NIL, no brackets are used. 
# rpars is initialized to 4. | 


nt 121 


15 the starting column for comments. Initial setting is 48. 


Comments run between firstcol and linelength. If a word in a 
comment ends with a "." and is not on the list abbrevist, and the - 
position is greater than halfway between firstcol and linelength, the 
next word in the comment begins on a new line. Also, if a list is 
encountered in a comment, and the position is greater than halfway, 
the list begins on a new line. | 


If a comment is bigger (using count) than prettylcom in size, it is 
printed starting at column 10, instead of firstcol. ^^ prettylcom 15 


initialized to 14 (arrived at empirically). | 


in the interests of efficiency, prettyprint approximates the number 
of characters in each atom, rather than calling nchars, when 
computing how much will fit on a line. This procedure works 
satisfactorily in most cases. However, users with unusually long 
atoms in their programs, e.g. such as produced by clispify, may 
occasionlly encounter some glitches in the output produced by 


prettyprint. The value of #carefulcolumns tells prettyprint how 


many columns (counting from the right hand margin) in which to 
actually compute  nchars instead of approximating. Setting 
#carefulcolumns to 20 or 30 will eliminate the above glitches, 
although it will slow down prettyprint slightly. #carefulcolumns is 
initially 0. | 


widepaper[T] sets filelinelength to 120, firstcol to 80, and prettylcom 
to 28. These are uscful settings for prettyprinting files to be listed 


оп wide paper. widepaper[] restores these parameters to their initial 


values. Тһе value of widepaper is its previous setting. 


If car of an expression is eq to commentflg, the expression is 


treated as a comment. commentflg is initialized to *. 


Note that makefile, page 14.64, resets linelength to the value of filelinelength, before calling prettydef. filelinelength 


is initially 72. 


Comments are also printed starting at column 10, if their sccond element is also a ", ie., comments of the form 


(* * ғ), 
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prettyprintmacros 
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changechar 
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Prettyprint 


If prettyflg is NIL, printdef uses prin2 instead of prettyprinting. 
This is useful for producing a fast symbolic dump (sce FAST option 
of makefile, page 14.64). Note that the file loads the same as if it 
were prettyprinted. prettyflg is initially set to T. 


used to inform prettyprint to call clispify on selected function 


definitions before printing them. See Section 23. 


is an assoc-list that enables the user to format selected expressions 
himself. car of each expression being prettyprinted is looked up on 
prettyprintmacros, and if found, cdr of the corresponding entry is 
applied to the expression. If the result of this application is NIL, 
prettyprint will ignore the expression.This gives the user the option 


of printing the expression himself in whatever format he pleases. If - 


the result is non-NIL, it is prettyprinted in the normal fashion. This 
gives the user the option of computing some other expression to be 


prettyprinted in its place. prettyprintmacros is initially NIL. 


is a list of elements of the form (typename . fn). For types other 


than lists and atoms, the type name of each datum to be 


prettyprinted is looked up on prettyprintypemacros, and if found, 
the corresponding function is applied to the datum about to be 


* 


printed, instead of simply printing it with ріп. — 


prettyprintypemacros is initially NIL. 


is an assoc-list that enables user to tell prettyprint to treat a 
car-of-form the same as some other car-of-form, eg. if 
(QLAMBDA . LAMBDA) appears on prettyequivist, then QLAMBDA 
expressions will be  prettyprinted the same as LAMBDA’s. 
prettyequivlst is initially NIL. a 


if non-NIL, and prettyprint is printing to a file or display terminal, 
prettyprint prints changechar in the right hand margin while 


printing those expressions marked by the editor as having. been 


changed (see Section 9). changechar is initially |. 


A comment of this form causes x to be evaluated at prettyprint 


+ + + + + 


time, eg, (* Е (RADIX 8)) as a comment in a function Н 


containing octal numbers can be used to change the radix to 
produce тоге readable printout. The comment is also printed. 


Prettyprint contains a facility for printing elements of various classes, e.g user functions, system + 
functions, clisp words, comments, ctc., in different fonts to emphasize (or deemphasize) their 
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importance, and іп general to provide for more pleasing printout when printing to a file. Of 
course, in order to be useful, this facility requires that the user has access to a printer which 
supports multiple fonts, such as an ХОР. 


Prettyprint signals font changes by inserting a user-defined escape sequence, e.g. tFtC meaning 
change to font 3, tFtA change back to font 1, etc. It is convenient if these sequences can consist 
of control characters, because by making these characters be separator charactors in filerdtbl, a file 
with font changes in it can also be loaded back in. Otherwise, the user would have to dump two 
files, one for listing, and one for loading. 


. Currently, the user can specify fonts for each of the following eight classes: 


lambdafont 


clispfont 


commentfont . 


userfont 


Systemfont 


changefont 


prettycomfont 


defaultfont . 


123 


124 


14 


the font for printing the name of the function being prettyprinted, 
before the actual definition (usually a large font). 


if clispflg is on, the font for printing any clisp words, ie. atoms | 


with property CLISPWORD. 


the font for everything inside of a comment. 


the font for the name of any function in the file, or any member of 


the list fontfns. 


the font for any other (defined) function. 


the font for anything in an expression marked by the editor. as 
having been changed. 


the font used in printing the operand of a file package command. 


the font for everything else, or any of the above classes for which a 
font is not specified. 


None of this section pertains to prettyprinting to the terminal. 


each different, or the same for several classes. Note: the output primitives print, prinl, etc., currently do not know 


about variable width fonts, so the user may have to experiment to find a compatible (pleasing) set of fonts. Note also 
that the user does not set lambdafont, clispfont, et al, but indicates what font to be used by including an appropriate 
entry in the fontprofile, page 14.51. fontset, described below, will then set lambdafont, clisfont, et al, to a data 
structure that contains the necessary information for performing the font change. 
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For example, the function on page 14.47 is shown on page 14.53 with lambdafont corresponding 
to HELVETICA12 BOLD, commentfont to TIMESROMANG ITALIC, userfont to HELVETICALO 
BOLD, and defaultfont to GACHA10. | 


The operation of the font package is affected by a large number of parameters, e.g. filelinciength, - 
listfilestr, etc. plus the various fontnames themselves. To facilitate switching back and forth: 


between various configurations, the font package allows the user to set the various parameters to 


their desired values, and then use the function fontname to package up and save this configuration. 


Subsequently, the user invokes this configuration by performing fontset[name]. 


 fontescapechar the character or string used to signal the start of a font escape 
sequence, | | | | 
fontprofile | list of elements of the i (fontclass NIL font&£), P5. here 


fontclass is one of the eight font classes and font is the font number 
for that class. For each fontclass, the escape sequence consisting 
of fontescapechar followed by the character code for the font 
number, i.e. for font number 1, tA, for font number 2, ТВ, ес. _ 


If font is NIL for any fontclass, the defaultfont is used. Note that. 


the defaultfont must be specified or an error is generated. 


fontchangeflg if T, enables fonts, if NIL, disables fonts, ie. no юш changes are 
performed when pipo braune; | | 


listfilestr - passed to the ЕТА system by listfiles. Can be used to specify 
subcommands to the LIST command, eg. to establish 
correspondance between font number and font name. 


commentlinelength since comments are usually printed in а smaller font, 


commentlinelength is provided to offset the fact that Interlisp does 


not know about font widths. Its value is a dotted pair of numbers. 
When fontchangeflg = T, car of commentlinclength is the linelength 
used to print short comments, i.e. those printed in the right margin, 
and cdr is the linelength used when printing full width comments. 


Note that the user may also want to reset filelinelength, prettylcom and firstcol да: described 
earlier) as a part of various font configurations. 


125 


The NIL is a place marker. fontname replaces (rplaca) cadr when the font configuration is defined. 


126 it is assumed that the user has some way of communicating to the printing device the correspondence between font 


numbers and fonts. 
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- fontdefsvars 


fontname[name] 
fontset[name] 


changefont[fontclass] 


fontdefs 
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the list of variables to be packaged by a fontname. initially 


fontchangeflg, filelinclength, commentlinelength, firstcol, prettylcom, 
listfilestr, and fontprofile. 


performs some processing on fontprofile, and then collects names 
and values of variables on fontdefsvars, and saves them on fontdefs. 


restores font configuration for name. Generates an error if name 
not previously defined. 


e.g. (CHANGEFONT LAMBDAFONT), (not ' LAMBDAFONT), prints the 


font escape sequence to change to fontclas. For use іп 


prettyprintmacros. 


| the dictionary of font configurations. fontdefs is a list of elements 
of form (name . parameter-pairs). To save a configuration on a file 


after performing a fontname to define it, the user could either save 
the entire value of fontdefs, or simply use an ALISTS file package 
command to dump ‹ out just the one configuration. 
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(BREAKCOM 
[LAMBDA (BRKCOM BRKFLG) (* Interprets a 
single command) | 
(PROG (BRKZ) 
TOP (SELECTQ 
BRKCOM 
[t (RETEVAL (QUOTE BREAK1) 
(QUOTE (ERROR ]] 
(GO (* Evaluate BRKEXP 
unless already evaluated 
print value, and exit.) 
(BREAKCOM1 BRKEXP BRKCOM NIL BRKVALUE ) 
(BREAKEXIT) ) = 
(OK (* Evaluate BRKEXP, 
unless already evaluated, 
do NOT print value, 
and exit.) 
(BREAKCOM1 BRKEXP BRKCOM BRKVALUE BRKVALUE ) 
(BREAKEXIT T)) 


(tWGO (* Same as GO except 
never saves evaluation 
on history.) 

(BREAKCOM1 BRKEXP BRKCOM T BRKVALUE ) 
(BREAKEXIT) ) 
(RETURN 


(* User will type in expression to be evaluated and 
returned as value of BREAK. Otherwise same as СО) 


(ВВЕАКСОМ1 [SETQ BRKZ (COND 
(BRKCOMS (CAR BRKCOMS )) 
(T (LISPXREAD Т] 
(QUOTE RETURN) 
NIL NIL (LIST (QUOTE RETURN) 
BRKZ)) 
(BREAKEXIT)) 
(EVAL -© (* Evaluate BRKEXP but 
do not exit from BREAK.) 
(BREAKCOM!1 BRKEXP BRKCOM) | 
(COND 
(BRKFLG (BREAK2) 
(PRIN1 BRKFN T) 
(PRIN (QUOTE " EVALUATED | 


") 


T))) 
(ФЕТО !VALUE (CAR BRKVALUE)) 
(* For user's benefit.) 
) 
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14.9 FILE PACKAGE? 1% 


This section describes the file package: a set of functions, conventions, and interfaces with other 
system packages for facilitating the bookkeeping involved with working in а large system consisting 
of many symbolic files and their compiled counterparts. Essentially, the file package removes from 
the user the burden. of keeping track of where things are and what things have changed. For 
example, the file package keeps track of which file contains a particular datum, e.g. a function 
definition, record declaration, etc., and, in many cases, will automatically retrieve the datum when 
necessary if it is not already in the user’s working environment. The file package also keeps track 
of which files have been in some way modified and need to be dumped, which files have been 
dumped, but still need to be listed and/or recompiled. АР 


The file package requires that for each file, the value of the atom fileCOMS, be a list of Ме package 
commands which describe how to write out the file, e.g. for the file FOO, the command list would 
be the value of the variable FOOCOMS. Thus, if the file FOO is to contain function definitions for 
the functions A and B and values for the variables C and D, its command list would be 


((FNS А B) (VARS C D)). FNS and VARS аге the names of the file package commands for 
‘the function and variable file package types, and the remainder of the command specifies the 


elements whose "definitions" of the respective type are to be written on the Ме. With FOOCOMS 
set as above, makefile[FOO]!2? will actually place on the file FOO expressions which, when evaluated 
as FOO is loaded, will restore the various definitions. Such a command list can be constructed by 
simply setting and editing the fileCOMS variable. However, the file package contains facilities 
which make constructing and updating command lists easier, and in some cases automatic. These 
are described in detail below. | 


All the system functions that perform global file operations, 99 e.g., load, loadfns, prettydef, tcompl, 
recompile, et al, as well as those functions that define or change data, e.g., editf, editv, editp, 
DWIM corrections to user functions, typed-inP! assignment of variables or property values etc., 
interact with the file package. Some of these interactions are quite complex. For example, the same 
function may appear in several different files, or the symbolic or compiled files may reside in other 
directories, or were originally made under a different name, etc. Therefore, this section will not 
attempt to document how the file package works in each and every situation, but instead make the 
deliberately vague statement that it does the "right" thing with respect to keeping track of what has. 
been changed, and what file operations need to be performed in accordance with those changes. 


127 The file package was written by W. Teitelman, and extended by L. M. Masinter and R. M. Kaplan. The notion of a 
typed definition, and the designing and implementing of type-indepedent ways of manipulating the 
name-definition-type-file associations, belong to L. M. Masinter 

128 The file package can be disabled by setting filepkgflg to NIL. 

129 Al file operations in the file package are based on the root name of the file, i.e., the filename with version number 
and/or directory field removed, but extension, if any, included. In other words, the user could also have said 
makcefile[CKAPLAN» 200. ; 27). 

130 as opposed to "local" file operations such as those performed by print, read, setfileptr, etc. 

131 


ie. if the user types in (PUTPROP 'F00 prop expression), this is noticed by the file package. If a program executes 
the above, it is not. 
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TYPED DEFINITIONS 


. In addition to the definitions of functions and values of variables, source files in Interlisp can 


contain a variety of other information, e.g. property lists, record declarations, definition of edit 
macros, hash arrays, etc. In order to treat uniformly from the standpoint of file operations such a 
diverse assortment of data, we introduce the concept of a typed definition, of which a function 
definition is just one example. We say that a definition associates with a name (usually a literal 
atom), a datum, the definition, of a given type (called the file package type). Since the same name 
may have several definitions, (e.g. a given atom may have both a function definition and a 


| variable-valuc definition), it is important to think of a typed definition as a relation between three 


elements: the name, the definition, and the type. 


The file package includes mechanisms for creating, destroying, and editing typed definitions, and 
for moving definitions from one file to another, or from one name to another. For example, the 
primitive functions for creating and destroying function and variable definitions are putd and setq, 
and they are edited with editf and editv respectively. There is also a need to move definitions 
from the user’s current core image to a symbolic file, or vice versa. This adds a fourth element to 
the notion of a definition, namely the file where the typed definition of a particular name resides. 


Whenever the user defines, edits, or otherwise changes a datum of a particular file package type, 
the corresponding system functions inform the file package that such new items have been defined 
or old definitions modified. The file package maintains a "database" of this information, so that it 
can tell the user (via the function files?) what files need to be rewritten, listed, or recompiled, and 
ask him where new definitions should be stored in the case that they do not appear on the 
fileCOMS of any file (by calling addtofiles?). The function cleanup will execute all the operations 
necessary to make the user’s permanent files consistent with the definitions in his current 
core-image. | 


In addition, the file package provides: 
(1) A uniform way of augmenting a file’s command list to include new items of a given file 


package type, the function addtofile. The function addtofile will either construct a new command 
appropriate for the given file package type, or add the new name to an already existing command 


for dumping items of that type, taking into account special information about the uses and formats 


of the different commands. 
(2) A uniform way of deleting items from a file’s command list, the function delfromfile. 


(3) A simple way of determining whether an item of a given type resides on a particular file or 
whether any items of that type reside on the file, the function infilecoms?. 


(4) A way of determing what files contain definitions of a given type for a particular name, the 
function whereis. 


(5) A way of comparing alternative definitions of the same name, or definitions of different names, 
the functions compare and comparedefs. 


(6) Type-independent ways of manipulating Ше патс- -definition- -type-file associations, via the 
functions getdef, putdef, copydef, editdef, etc. 


To provide these facilitics, the file package must have considerable information about each of the 
various file package commands and file package types. For the file package types and commands 


described below, this information has already been provided, and the user can simply invoke the 
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appropriate defining and editing functions, and then specify the appropriate file package 
commands, or allow the file package to construct the commands automatically. The user may also 
define new file package types by specifying how the system should operate with respect to 
definitions of that type via the function filepkgtype. Similarly, the user may define new file package 
commands by specifying the relationship between that command and the various file package types 
via the function filepkgcom. The methods for defining new file package types and commands will 
be discussed later (page 14.72). First, the built-in file package types and their associated 
commands will be described. | 


FILE PACKAGE COMMANDS 


The basic mechanism for creating symbolic files is the function makefile, described in detail on. 
page 14.64. makefile takes as its first argument a file name. It extracts the namefield of the file, 
packs COMS onto the end of it, and treats the value of the resulting atom as the file command list , 

ie. alist of file package commands. E.g. makefile[FOO. ; 27] will use the value of FOOCOMS as file 
command list. | | | 


File package commands сап Бе used to save on the output Ме definitions of functions, values of 
variables, property lists of atoms, arrays, advised functions, edit macros, record declarations, etc. 
The interpretation of each file package command is as follows: 


1. (FNS бу ... fnm), а defineq is written with the definitions of бој ... ба 132 


2. (VARS var. . vary), for each var, an expression will be written which will set its top level - 
value when the file is loaded. If var; is atomic, var; will be set to the top-level value it had at 
the time the file was written, ie., (RPAQQ varj top-level-value) is written. 133 134 If vari is 
non-atomic, it is interpreted as (var fom) eg. 
(FOO (APPEND FIE FUM)) or (Ғ00 (QUOTE (Ғ001 FOO2 Ғ003))). In this case, the 
expression (RPAQ var form) is written. | 


3. (ADDVARS (vary . 1544) ... (var, ‚ Ist). for each (var; ist). writes an addtovar expression 
such that each element of Bt "that is not a member oft the value of var; at the time the file is 
loaded is added to уат;, i.e., the new value of var; will be the union n of its old value and 156. . 
e.g. (ADDVARS (DIRECTORIES LISP LISPUSERS) ) will add LISP and LISPUSERS to 

· the value of directories. var; can initially be NOBIND, in which case it is first set to NIL, Те. 
( ADDVARS (уаг)) can be used to initialize var to NIL if var has not previously been set. | 


4. (ALISTS (alistname; atom, atom; ...) ... (alistname, atom3 atom, ...)), alistname; is the пате 


132 The user should never print a DEFINEQ expression directly onto а file himself, but should instead always use the 


FNS command for dumping functions. For more details, see footnote on page 14.41. 


rpaqq and град are like 56144 and setq, except that they also perform some special operations with respect to the file 
package. 


134 Тіс HORRIBLEVARS Піс package command described below provides a way of saving and rcloading variables whose _ 


. values contain re-entrant or circular list structure, user data types, arrays, or hash arrays. 
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of an alist, ie. a variable whose value is an association list, e.g. editmacros, baktracelst, etc. 
For each alistname,, writes out expressions which will restore the ' corresponding entries, e.g. 
(ALISTS ( BREAKMACROS BT BTV)) will dump the definition for the BT and BTV 
commands, 


( PROP | propname atom, ... atom,) an appropriate putprops will be written which will restore 
the value of erie for each atom; when the file is 2 If propname is а list, 
expressions will be written for each pro property on that list. If pr y ame=ALL, the values of 
all user properties (on the property list of each atom) are ind 


(IFPROP propname atom, ... atom 
properties that actually appear on the property list of the corresponding atom. For example, 
if 2001 has property PROP1 and PROP2, #002 has PROP3, and ЕООЗ has property PROP1 
and PROP3, (IFPROP (PROP1 PROP2 PROP3) Ғ001 F002 F003) will Save oniy those 5 
property values. 


(PROPS (atom, ргорпате)) ... (atom, propname,)), similar to PROP command. An 
appropriate putprops За be written which will restore the value of propname, for each atom; 
when the file is loaded. 


(P. — M: each S-expression following P will be otinted ' on the output file, and 
consequently evaluated when the file is loaded. | 


(E.forms), each form following E will be evaluated at output time, i.e., when makefile 
reaches this command. 


(COMS соту ...com,), each of the commands com, .. сот, will be interpreted as a file 
package command. | 


(* . text), used for иван а comment іп а Ше. First а form-feed is printed, then the 
comment. 


Some alists are handled specially, e.g. usermacros, lispxmacros, etc. all of which have their own file package 
commands. | 


If atom, does not have the property propname (as opposed to having the property with NIL value), a warning 
жш, "NO ргорпате PROPERTY FOR аќот.". is printed. The command IFPROP сап be used if it is not 


known whether or not an atom will have the corresponding property. 


sysprops 15 а list of properties used by system functions. Only properties лог on that list are e dumped when the ALL 


_ option is used. 


NIL value), a warning кони "NO Огорпате PROPERTY FOR mm is рше. 
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(ADVISE fn ... fn,,), for each fn, appropriate expressions will be written which will reinstate 
the function to its advised state when the file is loaded. See Section 19. 


(ADVICE fn, ... p^ for each fn; will write а putprops which will put the advice back оп 
the property list of the function. The user can then use readvise to reactivate the advice. 


(USERMAC ROS atom, .. atom,), each atom; is the name of a user edit macro. Writes 
expressions for adding ‘the edit t macro definitions of atom; to usermacros, and adding the 


names of the commands to the appropriate spelling lists. 


(FILEPKGCOMS atom; ... atom,), each atom; is either Ше name of а user-defined file 
package command (see page 14. 4.73) or a user-defined Ме package type (or both) Writes 
expressions which will restore each command/type. 140 


(LISPXMACROS atom, ...atom,), Each atom; is а lispxmacro ог lispxhistorymacro 
(Section 22). Writes expressions which will save and restore the definition for each macro, as 
well as making the necessary additions to lispxcoms 


(RECORDS recy ... rec 2 where тесі .. rec, are the names of records (Section 23), writes 
expressions which will redeclare the ie records 15 when the file is loaded.! 


(I.S.OPRS оргу .. орг), where оргу .. opr, are the names of user-defined i.s.oprs 
(Section 23), writes expressions which will redefine the i.s.oprs when the file is loaded. | 


(TEMPLATES atom, .. atom p. where atom, .. atom, have Masterscope templates 
(Section 20), writes expressions Which will restore the templates when the file is loaded. 


(BLOCKS block, .. block,), for each Боск, a declare expression will be written which the 
block compile functions interpret as block declarations. See Section 18. 


(DECLARE: . filepkgcoms/flags), Normally expressions written onto a symbolic file are (1) 
evaluated when loaded; (2) copied to the compiled file when the symbolic file is compiled 


If atom, is not a user macro, a warning message "no EDIT MACRO for atom 4 " is printed. 


If atom, is not a file package command or pe a warning message "no FILE PACKAGE COMMAND for atom," 
is printed. 


The file package command INITRECORDS can be used to write expressions on a file that will, when loaded, perform | 
whatever initialization/allocation is necessary for the indicated records, but not to write out, and hence cause to be 
read back in, the record declarations themselves. This facility is uscful for building systems on top of Interlisp, in 
which thc implemcntor may want to eliminate the record declarations from a production version of the system, but 
the allocation for these records must still be done, 
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(see Section 18); and (3) not evaluated at compile time. DECLARE: allows the user to 
override these defaults. The output of those file package commands appearing within the 
DECLARE: command is embedded in a DECLARE: expression, along with any tags that are 
specified, e.g., (DECLARE: EVALGCOMPILE DONTCOPY (FNS --) (PROP --)) would 
produce (DECLARE: EVAL@COMPILE DONTCOPY (DEFINEQ --) (PUTPROPS --)). 
DECLARE: is defined as an nlambda nospread function. When declare: is called, it processes 
its arguments by evaluating or not evaluating each list depending on the setting of an internal 
State variable. The tags EVALGLOAD, ог DOEVAL@LOAD, and DONTEVAL@LOAD can be used 
to reset this state variable. The initial setting is to evaluate. The tag EVAL@LOADWHEN can be 
used to provide conditional evaluation. The value of the expression immediately following 
the tag determines whether or not to evaluate - 1... expressions when loading, i.e. ... 
EVALGLOADWHEN T ... is equivalent to ... EVAL@LOAD .. 


(MACROS atom; ... atom,) writes out the MACRO properties for each atom, embedded in a 
DECLARE: ЕСЕ Equivalent to > (DECLARE:  EVAL@COMPILE 
(PROP MACRO atom; ... atom,). See Section 18. 


(SPECVARS . vars) (LOCALVARS . vars) (GLOBALVARS. vars), outputs corresponding 
compiler declaration embedded in a DECLARE: DOEVAL@COMPILE DONTCOPY. See 
Section 18. 2A 


(UGLYVARS var] .. var n5 like VARS, except that the value of each var may contain 
structures for which read 5 not ап inverse of print, е. 5. о readtables, user data types, etc. 
Uses hprint package (page 14.59). | | 


(HORRIBLEVARS var, ... varp), like UGLYVARS except structures may also contain circular | 


pointers. Uses hprint package (page 14.59).1? The values of var) .. var, are printed in the 
same operation, so that they may contain pointers to common substructures. 


(ARRAY vary .. ‚ Vary), each var; following ARRAY should have an array as its value. An 
appropriate expression will be 4 written which will set the variable to an array of А {һе 
same size, type, and contents upon Тоадјар.1“4 


As indicated in Section 18, DECLARE: expressions are specially processed by the compiler. In this case, the relevant 
tags are COPY, DOCOPY, COPYWHEN, DONTCOPY, EVAL@COMPILE, DOEVAL@COMPILE, 

EVALGCOMPILEWHEN, DONTEVAL@COMPILE, FIRST, and NOTFIRST. The value of declaretagslst is а list of 
all the tags used in DECLARE: expressions. If a tag not on this list appears in a DECLARE: file pague command, 

performs spelling correction using declarctagslst as a spelling list. 


UGLYVARS does not do any checking for circularities, which results in a large speed and internal-storage advantage 
over HORRIBLEVARS. Thus, if it is known that the data structures do not contain circular pointers, UGLYVARS 
should be used instead of HORRIBLEVARS. Шш 


assuming that the clmements of the array are objects for which read is an inverse of print. Otherwise, UGLYVARS or 


HORRIBLEVARS should be used. 
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27. (ORIGINAL com; .. com,), each of the commands will be interpreted as a file package 
command without regard to any file package macros (see below). Useful for redefining a 
built-in file package command in terms of itself. 


In each of the commands described above, if the atom + follows the command type,!^? the form 


following the *, ie, caddr of the command, is evaluated and its value used in executing the 
command, e.g., (FNS * (APPEND FNS1 FNS2)). When this form is atomic, i.e. a variable, e.g. 
(FNS * FOOFNS), we say that the variable is a filevar. Note that (COMS * form) provides a way 
of computing what should be done by makefile. | | | 


New file package commands can be defined or built in commands redefined via the function 
filepkgcom (page 14.73). New file package types can be defined or built in types redefined via the 
function filepkgtype (page 14.72). Both file package commands and file package types can be 
dumped via the FILEPKGCOMS command. If a file package function is given a command or type 
that is not defined, it attempts spelling correction!^9 using filepkgcomsplst as a spelling list. If - 
successful, the corrected version of the list of file package commands is written (again) on the 
output Ніе,147 If unsuccessful, generates an error, BAD FILE PACKAGE COMMAND. 


Example: | 
-SET(FOOFNS (F001 F002 Е003)) 
-SET(FOOCOMS((FNS * FOOFNS) (VARS ЕТЕ) 
(PROP MACRO Ғ001 ЕОО2) (P (МОМО (QUOTE Е001) (QUOTE FIE1] 
-MAKEFILE(FOO) | 
would create a file Ғ00 containing: 
1. (FILECREATED "time and date the file was made" . "other information") 
2. (PRETTYCOMPRINT FOOCOMS) 
3. (RPAQQ FOOCOMS ((FNS * FOOFNS) ...) 
(RPAQQ FOOFNS (Ғ001 F003 F003)) 
.  (DEFINEQ "definitions of F001, F002, and F003") 


4 

5 

6. (RPAQQ ЕТЕ "value of ЕТЕ") 

7. (РОТРКОРЅ F001 MACRO propvalue) 
8 


(PUTPROPS Ғ002 MACRO propvalue) 


145 Except for the PROP and IFPROP commands, in which case the * follows the property name, eg, 


(PROP MACRO * FOOMACROS). 


146 unless dwimflg or nospellflg=NIL. See Section 17. 


147 since at this point, the uncorrected list of file package commands would already have been printed on the output file. 


When the Піс is loaded, this will result in fileCOMS being reset, and may cause a message to be printed, e.g., 
 (FOOCOMS RESET). The value of FOOCOMS would then be the corrected version. 
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9. (МОМО (QUOTE F001) (QUOTE FIE1)) 


10. STOP 
This completes the description of file package commands, 


FILE PACKAGE TYPES 


A file package command is an instruction to makefile to perform an explicit, well-defined 
operation, usually printing some expression(s). A file package type is an abstract notion of a class of 
objects which share the property that every object of the same file package type is stored, retrieved, 
edited, copied etc., by the file package in the same way. Usually there is a one to one 
correspondence between file package types and file package commands, i.e. for each file package 


type, there is a file package command which is used for writing objects of that type to a file, and 


each file package command is used to write objects of a particular type. However, in some cases, 
the same file package type can be dumped by several different file. package commands. For 


example, the file package commands PROP, IFPROP, and PROPS all dump out the file package 


type РКОРЅ.148 It is also permissible for the same file package command to dump several different 


file package types. For example, the user can define а file package command which dumps both a- 
function definition and its macro. Conversely, some file package comands do not dump any file. 


package types at all, e.g. the E command. 


Thus, for each file package command, the file package must be able to йени: what ped 
definitions the command will cause to be printed so that the file package can determine on what 
file (if any) an object of a given type is contained. Similarly, for each file package type, the file 


package must be able to construct a command that will print out an object of that type. In other 


words, the file package must be able to map file package commands into file package types, and 


vice versa. Information can be provided to the file package about a particular file package 


command via the function filepkgcom, page is 73, and information about a pariicular file package 
type via the function filepkgtype, page 14.72.14 | 


The file package currently implements the following file package (уреѕ:150 FNS (functions), VARS 


148 This means if the user changes an object of file package type PROPS, e. g. via editp or a typed in call to putprop ог. 


ма an explicit сай to markaschanged (page 14.67), this object сап be written out with any of Ше above three 
commands. Thus, when the file package attempts to determine whether this typed object is contained on a particular 
file, it must look at instances of all three commands PROP, IFPROP, and PROPS, to see if the corresponding atom 
and property are specified. — 
149 In the absence of other information, the default is simply that a file package command of the form (FOO name) 
prints out the definition of name as a type 200, and, conversely, if name is an object of type FOO, then name can be 
written out by a command of the form (FOO name). | | | 


150 The value of filepkgtypes is a list of all file package types, including any that may have been defined by the user. | 
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(variables), ALISTS (alist entries)?! FI LEVARS. (filevars, page 14.60) PROPS (property 
name-value pairs)? EXPRESSIONS (expressions)? MACROS (compiler macros, Section 18), 
USERMACROS (user edit macros, Section 9), LISPXMACROS (lispxmacros and lispxhistorymacros, 
Section 22) ADVICE (advice, Section 19), FILEPKGCOMS (file package commands/types), 
RECORDS (records, Section 23), FIELDS (fields of records, Section 23), I.S.OPRS (iterative | 


Statement operators, Section 23), TEMPLATES (Masterscope templates, Section 20). | 


MARKING CHANGES . 


Operations in the file package can be broken down. roughly into three categories: (1) marking 
changes, (2) noticing files, and (3) updating files. The various system functions which create or | 
modify objects of the corresponding. type call. markaschanged (page 14. 67) to mark the- 
corresponding object as changed. 154 For example, when a function is defined via define or defineq, 


or modified either explicitly via editf, or implicitly, ма a DWIM correction, the function is marked 


as being a changed object of type FNS. Similarly, whenever a new record is declared, or an 
existing record redeclared or edited, it is marked as к а eee Mons of type RECORDS, and 
so on for all of the other file package types. 


Note that in some cases the marking procedure can be subtle; e.g. if the user edits a popat list 
using editp, only those properties whose values are actually changed (or added) are marked. As | 


mentioned earlier, some properties implement other file package types, eg. EXPR, ADVICE, 


MACRO, I.S.0PR, etc. For example, if the user changes the value of the property I.S.OPR, he Ж 
is really changing ап object of type I.S.OPR, and the effect is the same as though he had | 


redefined the i.s.opr via a direct call to the function is.opr. If a property whose value has been _ 


changed or added does not correspond to a specific file package type, then it is marked asa 


changed object of type PROPS whose name is (variablename propname).^ _ 


151 А variable is declared to have a value which is an association list, іе. a list of dotted pairs € via assoc. and 
putassoc, by putting on its property list the property VARTYPE with value ALIST. In this case, each dotted pair on- 

. the list is an object of type ALISTS: When the value of such a variable is changed, only those entries in the a-list 
that are actually changed or added are marked as changed (objects of type ALISTS). Objects of type ALISTS are 
dumped via the ALISTS or ADDVARS file package commands. Note that some a-lists "implement" other file package. 


types, e.g. the value of usermacros implements the file package type USERMACROS, the value of lispxmacros and 


lispxhistorymacros implements the file package type LISPXMACROS. This is indicated by having the value of the | 
· property VARTYPE be a list of the form (ALIST filepkgtype), e.g. getprop[LISPXHISTORYMACROS ; VARTYPE] = 

et LISPXMACROS). 
152 Note that some properties pice another file йе type, e.g. the property MACRO ae сы the file ш | 
type MACROS, the property ADVICE implements ADVICE, etc. This is indicated by the appearance of the property 
PROPTYPE on the property list of the property name, ie. getprop[MACRO; PROPTYPE]= MACROS. When such a 
property is changed ог added, an object of the corresponding file package type Бо marked. Ifo 
getprop[propertyname:PROPTYPE]= IGNORE, the change is ignored (ie. IGNORE cannot be the name of а file 
package type). FILE, FILEMAP, FILEDATES, etc. are all handled this way. Otherwise, when a property is 
changed or added, an object of type PROPS, with "name" (atom конш is marked as being changed. | 
153 Objects of type expressions are written out via the P file package command, and marked, as being changed via ш 
REMEMBER programmer assistant command, Section 22. 


154 The user can also call markaschanged directly to mark objects of a particular file package type as changed. 


155 except if the property name has a property PROPTYPE with value IGNORE as described earlier. 
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Similarly, if the user changes а variable which implements the Ше package type ALISTS (as 
indicated by the appearance of the property VARTYPE with value ALIST on Фе variable’s property- 
list), only those entries that are actually changed are marked as being changed objects of type | 


ALISTS, and the "name" of the object will be (variablename key) where key is car of the entry оп 
the alist that is being marked. If the variable corresponds to a specific file package type other than 
ALISTS, e.g. USERMACROS, LISPXMACROS, etc., then an object of that type is marked. In this 
case, the name of the object will be car of the corresponding entry on Ше a-list, e.g. if the user 
edits lispxmacros and changes a definition for the lispxmacro PL, then the object PL of type 
LISPXMACROS is marked as being changed. 


The section on Defining New File Package Commands/Types, page 14.73, tells how the user can 
change or extend the marking algorithm for particular file package commands or types. | 


NOTICING FILES 


Files are "noticed" by load and loadfns (or loadfrom, loadvars, etc.) or by makefile. Noticing a Ше 
consists of adding its root name to the list filelst, and adding the property FILE, value 
((fileCOMS . type)), to the property list of its root name, D9 157 where type indicates how the file was 
loaded, e.g., completely loaded, only partially loaded as with loadfns, loaded as a compiled file, etc. 
For example, if the user performs load[<TEITELMAN>FOO.LSP; 2], FOO.LSP is added to filelst, 
and ((FOOCOMS . T)) is put on the property list of FOO.LSP. 


The property FILE is used to determine whether or not the corresponding file has been modified 
since the last time it was loaded or dumped as described below. In addition, the property 
FILECHANGES contains the union of the names of all changed items, undifferentiated by type, 
since the file was loaded (і.е., there may have been several sequences of editing and rewriting the 
file), and the property FILEDATES a list of version numbers and the corresponding file dates. The 
use and maintenance of these корш is explained below. 


UPDATING FILES 


Periodically, the function updatefiles is called to find which file(s) contain the elements that have 
been сһапрей.158 updatefiles operates by scanning filelst and interrogating the file package 


156 The computation of the root name is actually based оп the name of the file as indicated іп the FILECREATED 
expression appearing at the front of the file, since this name corresponds to the name the file was originally made 
under. Similarly, the file package can detect that the file being noticed is a compiled file (regardless of its name), by 
the appearance of more than one FILECREATED expressions. In this case, each of the files mentioned in the 
FILECREATED expressions are noticed. For example, if the user performs ВСОМРІ ( (FOO FIE)), and subsequently 
loads FOO.COM, both FOO and FIE will be noticed. 


++ +++++++++ 


157 The variable loadedfilelst contains a list of the actual names of the files as loaded by load or loadfns. For example, if Е 
Ше user performs LOAD[<NEWLISP>EDITA.COM;3], EDITA will be added о Меј but 
<NEWLISP>EDITA.COM; 3 is added to loadedfilelst. loadedfilelst is not used by the file package, it is mantained for 
the user’s benefit. 

158 


updatefiles is called by files?, cleanup, and makefiles, 1.е., any procedure that requires the FILE property to be up to 
date. (The user can also invoke updatefiles directly.) This procedure is followed rather than update the FILE _ 
property afler each change because scanning filelst and examining each file package command can be a 
time-consuming process, and is not so noticcable when performed in conjunction with a large operation like loading 
or writing a file. 
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commands for each file. When (if) any files are found that contain the corresponding typed 
definition, the name of the clement is added to the value of the property FILE for the 
corresponding file. Thus, after updatefiles has completed operating, the files that need to be 
dumped are simply those files on filelst for which cdr of their FILE property is non-NIL. For 


example, if the user loads the file FOO containing definitions for F001, F002, and F003, edits 


2002, and then calls updatefiles, getprop[FOO; FILE] will be ((FOOCOMS . Т) F002). If any 


Objects marked as changed have not been transferred to the FILE property for some file, e.g., the 


user defines a new function but forgets (or declines) to add it to the file package commands for the 
corresponding file, then both files? and cleanup will print warning messages, and then call 
addtofiles to permit the user to specify on which files these items belong. 


Whenever a file is written using makefile, the elements that have been changed, 1.е., cdr of the 
FILE property, 2. moved to the property FILECHANGES, and cdr of the FILE property is reset 
(rplacd) to М11.59 In addition, the file is added (о the list notlisted files and notcompiledfiles. 
Whenever the user lists a file using listfiles, it is removed from notlistedfiles. Similarly, whenever a 
Ше is compiled by tcompl recompile, bcompl ог brecompile, the file is removed from 
notcompiledfiles. Thus at each point, the state of all files can be determined. This information is 
available to the user via the function files?. Similarly, the user can see whether and how each 
particular file has been modified (by examining the appropriate property values) dump all files 
that have been modified, list all files that have been dumped but not listed, recompile all files that 


have been dumped but not recompiled, or any combination of any or all of the above by using опе 
of the function described below. | 


FILE PACKAGE FUNCTIONS 


makefile[file;options;reprintfns;sourcefile] 


notices Ше if not previously noticed. ^ Performs 


linelength[filelinelength], and calls prettydef giving it NIL, file, 
. fileCOMS, риши. sourcefile, апа the list of changes as its 
arguments, restores original linelength, and then adds file to 
notlistedfilesl?! and notcompiledfiles.1 options is a list of options 
or a single option interpreted as follows: | 


ЕА5Т perform prettydef with prettyflg =NI L 


159 If the file was not on Џеј e.g., the user defined some functions and initialized the corresponding fileCOMS 


without loading a file, then the file will be "noticed" when it is written by makefile, ie. it will be added to filelst, 
and given appropriate FILE, FILEDATES and FILECHANGES properties. 


160 fileCOMS are constructed from the name field only, e.g., makefile[ FOO. TEM] will work. The list of changes is simply 
cdr of the FILE property, as described earlier, i.e, those items that have been changed since the last makefile. 
makefile merges those changes (using union) with those handled in previous calls to makefile, and stores the result 
on the property FILECHANGES. This list of changes is included in the FILECREATED expression printed at the 
beginning of the file by printdate, along with the date and version number of the file that was originally noticed, and 
the date and version number of the current file, i.e., this one. (these two version numbers and dates are also kept on 
the property F ILEDATE for various integrity checks in connection with remaking a file as described below.) 0 


161 except if the Ше has оп its property list the property FILETYPE with value DON'TLIST, or a list containing 
DON'TLIST. 

162 Files that do not contain any function definitions, or those that have on their property list the property FILETYPE 

with valuc DON' TCOMPILE or a list containing DON' TCOMPILE, are not added to notcompiledfiles, nor are they 

compiled even when options specifies C or RC. | 
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RC call recompile after prettydef, or brecompile, if there 
are any block declarations specified in fileCOMS. 


C calls tcompl after prettydef, ог bcompl, if there are any 
block declarations specified in fileCOMS. 


CLISPIFY perform prettydef with clispifyprettyfig=T, causing 
clispify (see Section 23) to be called on cach. function 
defined as an expr before it is prettyprinted.l 


NOCLISP performs prettydef with prettytranflg - T, causing the 
CLISP translations to be printed, if any, in place of 
the corresponding CLISP expressions, e.g., iterative 
-statements, record expressions, printout forms, etc.. 


LIST calls listfiles on file. 


REMAKE | ’remakes’ file, іе. copies the prettyprinted definitions 
of those functions that have not changed from an 
earlier version of the symbolic file, and only 
prettyprints those functions that. have changed. See 
discussion, page 14 77. 


МЕМ does not remake А1е.164 


Any other option is spelling corrected using the list makefileoptions. 
If spelling correction fails, makefile generates an error. : 


If a remake is лог being performed,!6? makefile checks the state of file to make sure that the entire 
symbolic file was actually loaded. If file was loaded as a compiled file, makefile prints the message 
"CAN'T DUMP: ONLY THE COMPILED FILE HAS BEEN LOADED." Similarly, if only some of 
the symbolics were load via loadfns or loadfrom, makefile prints "CAN' T DUMP: ONLY SOME OF 
ITS SYMBOLICS HAVE BEEN LOADED." In both cases, makefile will then ask the user if it 
should dump anyway, and if the user declines, makefile does not ; not сай prettydef, but simply returns 
(file NOT DUMPED) as its value. 


If F, ST, STF, or S is the next item on options following C or RC, given to the compiler as the 
answer to the compiler’s question LISTING?, e.g., makefile[ FOO;(C Е LIST) | will dump #00, 
then tcompl or bcompl it specifying that functions are not to be redefined, and finally list the file. 


The user can indicate that file must be block compiled together with other files as a unit by 


163 Alternatively, if file has the property FILETYPE with value CLISP or a list containing CLISP, prettydef is called 


with clispifyprettyflg reset to CHANGES, which will cause clispify to be called on all functions marked as having been 
changed. For more details, sce discussion of clispifyprettyflg in Section 23, Note that if file ħas property FILETYPE 
with value CLISP, the compiler will know to dwimify its functions before compiling them, as described in Sections 
18 and 23. | 
14 ү makefileremakeflg is T (its initial setting), the default for all calls to makefile is to remake. The NEW option is 
provided in order to override this default 


165 i.e., makefileremakeflg is NIL, or the option NEW was specified. " 
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putting a list of those files on the property list of cach file under the property FILEGROUP. For 
example, EDIT and WEDIT are one such group, DWIM, WTFIX, CLISP, and DWIMIFY another. 
If file has a FILEGROUP property, the compiler will not be called until all files on this property 
have ve been dumped that need to Бе. 


makefile operates by rebinding prettyflg, prettytranflg, clispifyprettyflg, and then under a resetlst, 
evaluating each expression on makcefileforms (under errorset protection), and then calling prettydef. 
The FAST, CLISPIFY, NOCLISP are all implemented via expressions on makefileforms, e.g. 
(AND (MEMB 'FAST OPTIONS) (SETQ PRETTYFLG NIL)). The user can add expressions to 


makefilefonms to implement his own options. 


makefiles[options; files] For each file on files that has been changed, performs. 


1166 


167 


168 


makefile[file;options]; If files=NIL,  filelst is used, ер. 


makefiles[LIST] will make and list all files that have been changed. | 
In this case, if any typed definitions for any items have been — 
defined or changed and they are not contained in one of the files 
on filelst, makefiles calls addtofiles? to allow the user to specify 
where these РО. Тһе value of makefiles is a list of all files that are 
· made. | 


listfiles[files] mE | nlambda, nospread function. Uses the function tenex (Section 21) 


to tell the operating : Ма to list each file in files (if NIL, 
notlistedfiles is used). 66 | 


Each file listed is removed from notlistedfiles if the listing is 
A completed, e.g., if the user control-C's to stop the listing and 
 QUITs. For each file not found, listfiles prints the message 

"file-name NOT FOUND" and proceeds to the next file on files. 


compilefiles[files] |  nlambda, nospread function. Executes the RC option of makefile | 
| | for each member of files. (If files=NIL, notcompiledfiles is 

и5ед.)167 | | 
cleanup[files] | . . nlambda, nospread. Dumps, lists, and recompiles (or brecompiles) 


any and all files on files requiring the aet рано If 
files = NIL, filelst is used. Value is NIL. 


listfiles calls the function listfiles] on each file to be listed. listfilesl calls tenex with concat[L IST$; filename;listfilestr],. 


where listfilestr is initially "2". The user can reset listfilestr to specify subcommands for the list command, or advise 
or redefine listfiles] for more specialized applications. - 


If car of files is a list, it is interpreted as the options argmument to makefiles. This feature can be used to supply an 
answer to the compilers LISTING? question, e.g., compilefiles[ (STF) | will compile each file on notcompiledfiles- 
so that the functions are redefined without the exprs being saved. 


The user can affect the operation of cleanup by ав the variable cleanupoptions, initially (LIST RC). For — 


example, if cleanupoptions is (КС Р), no listing will be performed, and no functions will be redefined as the result 
of compiling. Alternatively, if car of files is a list, it will be interpreted as the list of options regardless of the value 


of cleanupoptions. 
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Prints on terminal the names of those files that have been modified 
but not dumped, dumped but not listed, dumped but not compiled, 
plus the names of those functions and other prettytypes (if any) 
that are not contained in any file. If there are any, files? then calls 
addtofiles? to allow the user to specify where these go. 


type is a file package type. whereis sweeps through all the files on 
files and returns a list of all files containing name as a type. whereis 
knows about and expands all file package commands and 
filepkgmacros. type= ПГ defaults to F NS. If files is not a list, the 
value of a is изед.19 


ткыш ашы {уре; newflg] 


unmarkaschanged[name;type] 


. REMEMBER € 


filepkgchangesl[type;lst] 


addtofiles?[-] 


169 


marks name of type type as being changed. newflg is T for calls to 
markaschanged corresponding to the creation of name, e.g. from 
define, as opposed to calls corresponding to a change to name, e.g. 
from the editor. Value of markaschanged is name, markaschanged 
is undoable. i | 


unmarks (undoably) name of type ty pe as being changed. 179 Value 
is name if name was marked as changed and is now unmarked, 
NIL otherwise. | 


programmer assistant command (Section 22) Marks the events 


indicated by ¢ as changed objects of type EXPRESSIONS. 


lambda nospread. If Ist is not specified (as opposed to being NIL), 
value is a list of those objects of type type that have been marked 
as changed but not yet associated with their corresponding files. If 
Ist is specified, filepkgchanges sets the corresponding list. 
filepkgchanges[] returns a list of all objects marked as changed as a 
list of elements of the form (typename . changedobjects). 


called from makefiles, cleanup, and files? when, after updatefiles has 
finished operating, some objects remain that have been marked as 
changed for which no file containing them could be found. 
addtofiles? asks the user if he wants to say where the various 
changed items that do not belong to any file should be placed. If 


If the whereis package (Section 24) has been loaded, whereis is redefined so that files- T means use the whereis data 


base, i.e. whereis will find where x is even if the file has not been loaded or noticed. files - NIL always means:use 


filelst. 


170 


Provided that updatefiles has not been called since name was marked, thereby moving пате to the property list of 


the file(s) that contain it. See discussion page 14.63. 
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11 
 addtofiles? will check whether the item is the name of a list, ie. whether its value is а list. If not, the user will be 
asked whether it is a new list. | 


+++ 


++ + ++. 
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user answers N(o), returns NIL without taking any action. If the 
user answers |, this is taken to be an answer to each question that 


would be asked, and interpreted as described in (4) below, ie. al 


changed items are marked as dummy items by adding them to | 
NILCOMS. Otherwise, addtofiles? maps through all the changedlst's, 


(1) 


Ко 
(3) 


(4) 


O 


(6) 


prints each element, and accepts one of the following responses: 


a file name ог name of a list, e.g., FOO or FOOFNS.17! Adds 
the item to the а а Ме or list, using addtofile. 


line-feed - means same as the user S previous response. 


Space or carriage return - take no action 


| - item is marked as а dummy item by adding it to 


NILCOMS, i.e., tell file package not to worry about what to o 
do with this item. 


[ - the "definition" of the items in. saa are edad а” 
to the terminal, and then the user is asked again about their — 
_ disposition. | | » BL. 


© 


(2 addtofiles? prompts with "LISTNAME: (", the 1 user types | 

in the name of a list, ie. a variable whose value is a list, 2 
terminated by а ).172 item will then only be added to (under) | 
a command in which the named list appears as a filevar. If 


none are found, a message is printed, and the user is asked | 


again. For example, the user defines а new function F003, | 
and when asked where it goes, types (FOOFNS). If the . 
command (FNS * FOOFNS) is found, F003 will be added 
to the value of FOOFNS. If instead the user types 
(FOOCOMS), and the command (COMS * FOOCOMS) is 
found, then F003 will be added to a command for dumping 
functions that is contained in foocoms. 


@ - addtofiles? prompts with "NEAR: (“, the user types in 
the name of an object, and item is then inserted in a 
command for dumping objects (of its type) that contains the 
indicated name. item is inserted immediately after the 
indicated name. mE за И 


If the item is not the name of a file on filelst, the user will be asked whether it is a new бе. If he says no, then - 


(1) above. 


С If the named list is not also the name of a file, the user can [snp type it in without parenthesis as described under 
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FUNCTIONS FOR MANIPULATING TYPED DEFINITIONS + 
. Note: all functions described below adhere to the following conventions: | + 
(1) if a list argument is called for, e.g. files meaning a list of files, and an atom is + 
given, the function will operate as though list of that atom was given; E 

(2) type is a file package type. The singular form of the name of a type is also + 

recognized, e.g. type=VAR is equivalent to type=VARS. type=NIL is equivalent to + 

type = FNS; + 

(3) files=NIL is equivalent to files = filelst; + 

(4) source can be one of: | + 

NIL means the definition currently in effect if there is one, the saved + 

definition, or the definition from a file determined by whereis.!/ + 

0 means the definition currently in effect. + 

T | . means the "saved" definition, as stored by savedef. + 

FILE means the definition contained on the (first) file determined бу + 

whereis. T 

a file name means the definition contained on the indicated file. + 

All functions which make destructive changes are undoable. 0. | + 
Note: the operation of most of the functions described below сап be changed or extended by + 
modifying the appropriate properties for the SORTCSBORGINR file package type using the function + 
filepkgtype, described on page 14.72. t 
getdef[name;type;source;options] + 
Returns the s-expression definition of name, of type type, from + 

source.!/^ type is a file package type, eg. Е р. FNS, VARS, RECORDS. + 

For example, for (уре = FNS, a lambda expression is returned, 175 for + 

typc=VARS, the value of name is returned, ек. getdef also + 
recognizes type=FIELDS, in which case the list of record + 

declarations which contain name is returned, and type=FILES, in + 

173 called with files T, so that if the whereis package (Section 24) is loaded, this will use the whereis data base to find + 
the file containing the definition. + 

174 copying the definition unless options is or contains NOCOPY. | + 
175 ‘The definition will be dwimified if it is deemed likely to contain CLISP unless options is or contains NODWIM. + 
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| putdef[name;type;definition] 


| copydeffold;new; type;source] 
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which case the command list for the file is returned. 176 For all 
other types, getdef returns the s-expression which would be 
prettyprinted when dumping name as type. 


source is as described above. When source is a file name, getdef 
actually obtains the definition from the file. 


getdef causes an error if an appropriate definition cannot be found, 


unless ор tions is or contains NOERROR. 


defines name of type type with definition. For type=FNS, does a 
define; for type=VARS, does a saveset for type=FILES, 
establishes the command list, and notices name, etc. 


defines new to have a copy of the definition of old, i.e. essentially 
performs “4 putdef[new;subst[new;old:;getdef[old;type;source]]:type]. 
For type— FILES, copydef not only establishes the commands and 
notices new, as describe above, but also calls makefile to actually 


dump the file new. Eg. COPYDEF(PDQ RXT FILE) sets up 
RXTCOMS to be a copy of PDQCOMS, changes things like 


-© (VARS * PDQVARS) to be (VARS * RXTVARS) in RXTCOMS, 


deldef[name;type] | 


| showdef[name:type:file] 


i.e. getatomval[filecoms[name]]. 


and performs a makefile on RXT such that the appropriate 
definitions get copies from Е | 


Removes the definition of name as a ty pe that is currently in effect. 


| prettyprints the definition of name as a type to Ме, i.e. shows Ше 


user how name would be written to a file. used by addtofiles? (page 


Мм. 67). 


одидейпате; type;s Source; :coms] edits the definition of name with type type, i.e. essentially performs 


putdef[namoe;type;edite[getdef[;name;type;source];coms]]. 


savedef[name;type; definition} Makes definition (or if definition = NIL, the definition of name as a 


type that is currently in effect) be the "saved" definition for 1 пате 


-а5 а type. If type=FNS (or type=NIL), this consists of storing 


definition on name’s property list under property EXPR, CODE, or 
SUBR. For type=VARS, definition is stored as the value of Һе 
VALUE property. For other types, definition is stored in an internal 
data structure, from where it can be retrieved by getdef or 


 unsavedef. 


14.70 


File Package . 


unsavedef[name;type] Makes the "saved" definition of name as a type be the definition 
| currently in effect. As described іп Section 8, when type=NIL, 
unsavedef will unsave the EXPR property if any, else CODE or 
SUBR. unsavedef also recognizes type=EXPR, CODE, or SUBR, 
meaning to unsave the corresponding definition only 


+ + + + + 


loaddef[name;type;source] equivalent to putdef[name;type;getdef[name;type;source]]. loaddef is 
. essentially a generalization of loadfns, e.g. it enables loading a single 
record declaration from a file. Note that loaddef[fn] will give fn an _ 
expr definition, either obtained from its property list or а Ме, | 
unless it already has one. 


+ + + + + 


СИЗИН new;types;files;method] - 
Finds all of the places where old is used as any of the types in 
types and changes those places to use new. For example, 
changecallers[NLSETQ; ERSETQ] will change all calls to nlsetq to be 
calls to ersetq. Also changes occurrences of old to new inside the 
coms of any file, inside record declarations, properties, etc. . 


changecallers attempts to determine if old might be used as more 
than one type; e.g. if it is both a function and a record field. If so, | 
rather than performing the transformation of old-> new 
automatically, the user is поща to edit all of the plages where old old 
occurs. | 


Currently there are two different methods for determining which 
functions are to be examined. If method=EDITCALLERS, 
editcallers (Section 9) is used to search files. If 
method=MASTERSCOPE, then the Masterscope data base is used 
instead. method=NIL defaults to the value of 
defaultrenamemethod (initially EDITCALLERS). | 


ME M 


rename[old;new;types;files;method] 
First performs copydeffold: new;type] for all type inside types. It 
then calls changecallers to change all occurrences of old to new, and 
then "deletes" old with deldef. For example, if the user er has a 
function fool which he now wishes to call fie, he simply performs 
rename[FO01;FIE], and fie will be given fool’s definition, and all 
places that fool are called will be changed to call fie instead. 


+ + + + + + + 


compare[namel;name2;type;sourcel;source2] 
Compares definiton of namel with that of РАР 7 і.е. performs 
comparclists[gctdeffnamc1;type;source];getdef[name2;type; оше 
(see Section 5). 


++++ 


177 The latter method is more efficient if а Masterscope data base already exists, otherwise the functions on | files will 
have to be analyzed. 
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comparedefs[name; уре; sources] 
Calls comparclists on all pairs of definitions of name as a type 
obtained from the various sources. 


hasdef[name;type] | . returns T if name is the name of something of type type. 
typesoffname;-;-] | Returns a list of the types for which name has a definition. 


DEFINING NEW FILE PACKAGE TYPES 


The functions in the previous discussion provide type-independent ways of А typed E 


definitions, e.g. getdef[name;type] will obtain the definition of name regardless of which particular 
file package type is specified by type. This section describes how these Operations are specified for 
new file package types. 178 | 


filepkgtype[type;prop; ;val opip vala] 
ambda, 1 nospread function for defining new file package types, or 
scd attributes of existing file package types. prop is one of: 


GETDEF | val is a function of two arguments, name and (уре,179 which returns 
the current definition of name as a type type." Used by getdef. 


PUTDEF | val is a function of three arguments, name, type, and definition 
| which stores definition. Used by putdef. | 
DELDEF val is a function of two arguments, name, and type, which removes 
| the definition of of name as a type that is currently in effect. Used 
Бу deldef. 
NEWCOM val is a function of four arguments, name, type, listname, and file. 


Specifies how to make a new (instance of a) file package command 
to dump name, an object of type type. Used by addtofile and 
showdef. The function should return the new command. listname is 
non-NIL, means the user specified listname as the filevar in his 
interaction with addtofiles?. If no NEWCOM is specified, the default 
is to use defaultmakenewcom. dcfaultmakenewcom will construct 
and return a command of the form (type * filevar), where filevar is 
listname if listname is non-NIL, otherwise filevar is the value of 


178 ог respccified for existing file package types. 
179 The type argument is provided here and for the other properties so that the user may have the same function for 
more than one type. 


180 If there is no GETDEF property, a file package command for dumping name is created (by makenewcom). This 
command is then used to write the definition of name as a type type onto the file FILEPKG. SCRATCH, and this 
S-expression is then read back in and returned as the current definition. | 
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filecomslfile:typel. In either case, filevar will be set to list[name]. 
defaultmakenewcom can be advised or redefined by the user. 


WHENCHANGED val is a list of functions to be applied to name, type, and newflg 
(sce discussion of markaschanged, page 14.67) when name, an 
instance of type type, is changed or defined. Used for various 
applications, e.g. when an object of type I.S.OPRS changes, it is 
necessary to clear the corresponding translatons from clisparray.l? 


WHENFILED val is a list of functions to be applied to name, type, and file when 
| name, an instance of type type, is added to о file. 


DESCRIPTION val is a string which describes what instances of this type are, e.g. 
for type RECORDS, description is "record declarations". 


++ ++ +++++ ++ 


DEFINING NEW FILE PACKAGE COMMANDS 


This section describes how the user can specify the various attributes of a Ше package command 
for а new соттапӣ.18 


filepkgcom[commandname;prop; ;valy;...;prop,,;v | | 
тыда nospread nction for defining new file package commands, | 
or changing attributes of existing file package commands. prop is- 
one of; 


MACRO defines how to dump the file package command соттапдпате, 
Used by makefile. val is a pair (args . coms). The “arguments” to. 
commandname are substituted for args throughout coms, and the 
result treated as а list of file package commands.?83 For example, 
following filepkgcom[FOO;MACRO;((X Y) .coms)], then the file 
package command (ЕОО A B) will cause A to be substituted for X 
and B for Y throughout coms, and then coms treated as a list of 
commands!84 | 


ADD Specifies how (if possible) to add an instance of an object of a 
particular type to a given file package command. Used by addtofile. 
val is fn, a function of three arguments, com, a file package 
command саг of which is eq to commandname, name, a typed 


+ + + + НИ 000s ++ + 


181 Note: the WHENCHANGED function is called before the object is marked as changed, so that it can, in fact, decide 
that the object is лог to be marked as changed, and retfrom|MARKASCHANGED]. 


182 or respecify for an existing command. 


183 filevars are evaluated before substitution, i.e. If the atom * follows name in the command, caddr of the command is 


evaluated substituting in coms. 


++ + ++ 


184 


The substitution is carried out Бу subpair (Section 6), so that Ше “argument list" for the macro can also be atomic. 
For example, if (X. coms) was used instead of ((X Y). n then the command (FOO A B) would cause 
(A B) to be substituted for X throughout coms. 
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object, and type, its іуре.185 fn should return T if it (undoably) 

adds name to com, NIL if not. If no ADD property is specified, then 

the default is (1) if car[com]-type and cadr[com]=*, and 

caddr[com] is a filevar (i.e. a literal atom), add name to the value of | 

the filevar, ог (2) if car[com]=type and cadr[com] is not 5, add | 
name to cdr[com]. 


DELETE Specifies how (if possible) to delete an instance of an object of a 
particular type from a given file package command. Used by 
delfromfile. val is fn, a function of three arguments, com, name, 
and type, same as for ADD.. fn should return T if it  (undoably) 
deletes name from сот,!86 NIL if not. If no DELETE property is 
specified, then the gue is (1) if car[com] = type and cadr[com] ==, _ 
and caddr[com] is a filevar (ie. a literal atom), and name 5 
contained in the value of the filevar, then remove name from the _ 
filevar, or (2) if car[com] = type and cadr[com] is not *, and name is 
contained in cdr[com], then remove name from cdr[com]. | = 


CONTAIN Specifies whether an instance of an object of a given type is 
| | contained іп a given Ме package command. Used by whereis and 
infilecoms?. val is a function of three arguments, com, a Ме 
package command car of which is eq to commandname, name, and | 
type. The interpretation of name is as follows: if name is NIL, fn 
should return a list of elements of type type contained in com. If 
name is T, fn should return T if there are any elements of type type 
іп com. If name is an atom other than T or NIL, return T if name _ 
_ of type type is contained in com. Finally, if name is а list, reuma - 
list of those elements of type type contained in com that are also 
contained in пате.187 If the CONTAIN property is not provided, the 
command is simply expanded according to its MACRO definition, 
and each command on the resume command list is then 


Actually, the futon is given a fourth argument, near, which if non-NIL, means the function should try to add the 
item after near. See (6) 1 in discussion of addtofiles?, page 14.67. З 


If the Mindon returns the value of ALL, it means that the зай: is now “empty”, and can be | deleted entirely | 
from the command list. | А 


Note that it is sufficient for the CONTAIN function to simply return the list of items of type type in command com, 
іе. it can in fact ignore the name argument. The name argument is supplied mainly for those situations where 


producing the entire list of items involves significantly more computation or creates more storage than simply 


determining whether a pattiçuiat item (or any item) of type type is contained in the command. 
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interrogated, 188 189 


FUNCTIONS FOR MANIPULATING FILE COMMAND LISTS 


infilecoms?[name;coms;type;-] coms is a list of file package commands, or a variable whose value 


addtofile[name;file;type] . adds name of type type to the file package commands for file. Uses- 


is a list of file package commands. type is a file package type. If 
name=NIL, infilecoms? returns a list of all elements of type 
type.” If name=T, infilecoms? returns T if there are any 
elements of type type.! 191 Otherwise, infilecoms? returns Т if name 
is "contained" in coms. | 


addtocoms and makenewcom. Value is file. addtofile is undoable. 


delfromfiles[name;files;type] deletes all instances of name of type type from the file package 


addtocoms[coms;name;type;-;-] adds name as a type to coms, a list of file package commands or a 


188 


189 


190 


191 


192 


193 


commands for each of the files on files. If files is a non-NIL atom, 
list[files] is used. files=NIL defaults to filelst, i.e. delfromfiles[fn] 

—will delete the function fn from. all files that it appear on the user's 
current working environment.P?? Value is а list of files from which 
name was actually removed. Uses delfromcoms. geltromfiles is 
undoable. | 


Note that if commandname is а Ше package command that is used frequently, its expansion by the various parts of 
the system that need to interrogate files can result in a large number of conses and garbage collections. By informing 
the file package as to what this command actually does and does not produce via the CONTAIN property, this 
expansion is avoided. For example, suppose the user has a file package command called GRAMMARS which dumps 
various property lists but no functions. Thus, the file package could ignore this command when seeking information 
about FNS. 


If a CONTAIN property is specified and the corresponding function application returns NIL and car[com] = type, then 
the operation indicated by name is performed (1) on the value of caddr[com], if cadr[com] =", otherwise (2) on 
cdr[com]. In other words, by specifying a CONTAIN property that returns NIL, e.g. the function nill, the user 


specifies that a file package command of name ЕОО produces objects of file package type FOO and only objects of | 


type ЕОО. 
e.g. filefnslst and bcompl and brecompile use this option. 


makefile uses this option to determine whether the file contains any FNS, and therefore should be compiled, and if 
so, whether it contains any BLOCKS, to determine whether to call bcompl/brecompile or tcompl/recompile. 


whercis uses infilecoms? in this way. 


Deleting a function will also remove the function from any BLOCKS declarations in the fileCOMS. 
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variable whose value is a list of file package commands.!™4 Value is 
NIL if addtocoms was unable to find a command appropriate for 
adding name (0.175 addtocoms is undoable. 


delfromcoms[coms; name; type] deletes name as a type from coms. Value is NIL if delfromcoms 


makenewcom[name;type] 


was unable to modify coms to to delete name. 196 delfromcoms is 
undoable. 


value is a file package command for dumping name of type type. 


Uses the procedure described in the discussion of МЕМСОМ, page | 


14.72. 


moveitem[name; type;fromfile;tofile] 


Moves the definition of name as a type from fromfile to tofile by 


modifying the file commands in the appropriate way y (with 


filecomslst[file;type;-] 


Меј 81е] 


filecoms[file;type] 


smashfilecoms[file] 


194 


195 


196 


197 


delfromfile and addtofile). 


returns а list of items of type type in file, $ 
filecomslst[FOO ; MACROS], filecomslst[F O0 ; RECORDS], etc. 137 
filecomslst knows about expanding user defined file package 
commands. 


same as filecomslst[file; FNS]. 


same as pack"[file;or[type; COMS]]. e.g. filecoms[FOO] is the atom 
FOOCOMS, not the value of FOOCOMS. 


maps down filecomslst[file;FILEVARS] and sets to NOBIND all 
filevars, ie. any variable used in a command of the form 


- (command * variable). Also sets filecoms[file] to NOBIND. Value is 


file. 


Note that coms does лог have to correspond to a file command list, ie. the value of fileCOMS for some file. For 
example, coms can be the list of commands generated as a result of expanding a user defined file package command, 
Note also that the exact algorithm for adding commands depends the particular command itself. See discussion or 


the ADD property, in description 


Note: addtocoms will not attempt to add an item to any command which is inside of a DECLARE: unless the user 


specified a specific name via the 


See previous footnote. 


type can also be the name of a file package command, c.g. filcecomslst[file; а) will return the list of all BLOCKS 


declaration in file. 


of filepkgcom, page 14.73. 


LISTNAME or NEAR option of addtofiles?. 
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REMAKING А SYMBOLIC FILE 


. Most of the time that a symbolic file is written using makefile, only some, usually a few, of the 
functions that it contains have been changed since the last time the file was written. A considerable 
savings in time is afforded by copying the prettprinted definitions of those functions that have not 
changed from an earlier version of the symbolic file, and prettyprinting only those functions that 
have been changed. 198 makefile will o operate in this way, and remake the symbolic file, when 
makcfileremakeflg =T (its initial value). 19 When makefile is remaking a symbolic file, the user can 
either explicitly indicate those functions which are to be prettyprinted via the third argument to 
makefile, reprintfns, and indicate the file to be used for copying the rest of the function definitions 
from via the fourth argument to makefile, sourcefile.. The more typical useage however is to default 
both of these arguments to NIL. In this case, reprintfns will be set to those functions that have 
been changed since the last version of the file was written. For sourcefile, makefile obtains the full 
name of the most recent version of the file (that it knows about) from the FILEDATES property, 
and checks to make sure that the file still exists, and has the same file date as that stored on the 
FILEDATES property. If it does, makefile uses that file as -sourcefile.* In the case where the 
most recent version of the file cannot be found, makefile will attempt to remake using the original 
version of the file, i.e., the one first loaded, and specifying as reprintfns the union of all changes 
that have been made since the file was first loaded, which it obtains from Ше FILECHANGES 
property. If both of these fail, makefile prints the message "CAN'T FIND EITHER THE 
PREVIOUS VERSION OR THE ORIGINAL VERSION OF file, SO IT WILL HAVE TO BE 
WRITTEN ANEW", and does not remake the file, i.e. will prettyprint all of the functions. 


When a remake is specified, makefile also checks the state of the file (cdar of the FILE property) 
to see how the file was originally loaded (page 14.63). If the file was originally loaded as a 
compiled file, makefile will automatically call loadvars to obtain those DECLARE: expressions that 
are contained on the symbolic file, but not the compiled file, and hence have not been loaded. If 
the file was loaded by loadfns (but. not loadfrom), then loadvars will A be called to 

obtain any non-DEF INEQ expre CA лот | 


198 Remaking a symbolic file does лог depend on the earlier version having а file map, although it is considerably faster 


if one does exist. In the case of a remake where no file map is available, makefile scans the file looking for the 
corresponding definition whenever it is about to copy the definition to the new file. The scan utilizes skread (page 
14.16), and makefile does not begin scanning from the beginning of the file each time, but instead “walks through" 
the original file as it is writing the new file. Since the functions are for the most part in the same order, makefile 
never has to scan very far. However, makefile also builds a map of the functions it has skipped over so that if the 
order of functions is reversed in the new file, makefile is able to back up and pick up a function previously skipped. 
The net result is still a significant savings over (re)prettyprinting the entire file, although not as great a savings as 
occurs when a map is available. 


199 The user can override this default for particular files by specifying the NEW option in the call to makefile (page 


14.64). Or, the user can set makefileremakeflg to NIL and explicitly indicate those files which he wants to be remade | 
via the REMAKE option. 


This procedure permits the user to load or loadfrom a file in a different directory, and still be able to В 
makefile-remake. 


201 


If the file has never been loaded or dumped, е.р., the user simply set up the fileCOMS himself, then makefile will 
never attcmpt to remake the file, regardless of the зешпр of таксї leremakeflg, or whether ше ҢЕМАКЕ : option was 
specified. | | 
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PRETTY DEF FUNCTIONS . 


pretydefiprtfs prity file;prttycoms;reprintfns;sourcefile;changes] 


202 


Writes a symbolic file in prettyprint format for loading. prettydef 
uses filerdtbl as its readtable. The value of prettydef is the name of 
the symbolic file that was created. prettydef operates under а 
 resetlst (see Section 5). If an error occurs, or a control-D is typed, 
all files that prettydef has opened will be closed, the (partially | 
complete) file being written will be deleted, and any undoable | 
operations executed will be a 202 | 


prttyfns is ап пш list of function names.203 | 


| prttyfile is the name of the file on Which the output is to be 
written. If prttyfile=NIL, the primary output file is used. If _ 
prttyfile is atomic the file is opened if not already open, and it 
becomes the primary output file. prttyfile is closed at end of 
prettydef, and the primary output file is restored. Finally, if 
prityfile is a list, car of prttyfile is assumed to be the file name, and 
is opened if not already open. In this case, the file is left open at 
end of prettydef. 


prttycoms is a list of file package commands interpreted as 
described previously. If prttycoms is atomic, its top level value is- 


used and ап града is written which will set that atom to the list of _ E 


commands when the file is subsequently loaded. А prettycomprint 
expression (see below) will also be written which informs the user 

of the named atom. or list of commands when the file is 
Subsequently loaded. | 


reprintfns and sourcefile are for use in conjunction with remaking а 
file (see page 14.77). reprintfns can be a list of functions to be 
prettyprinted, or EXPRS, meaning prettyprint all functions with 
EXPR definitions, or ALL meaning pretty yprint all functions either 
defined as exprs, or with EXPR properties. sourcefile is Ше name 
of the file from which to copy the definitions for those functions - 
that are not going to be prettyprinted, i.e., those not specified by 
reprintfns. sourcefile=T means use most recent version (i.e. 


Since prettydef operates under a resetlst, any resetsaves executed in the file package commands will also be 


. protected, ie. restored. For example, if one of the file package commands executes a (RESETSAVE 


x 203 


204 


205 


(LINELENGTH 100)), the linelength will ошау be restored. 


prttyfns is an anachronism from when prettydef did not take as its third argument a list of file package commands. It 
is equivalent to including (FNS * prttyfns) in the file package commands, and is rarely used now. 


In addition, if any of the functions in the file are nlambdas, prettydef will automatically print a DECLARE: | 
expression suitable for informing the compiler about these functions, in case the user recompiles the file without | 


having first loaded the nlambda functions. For more discussion, see Section 18. 


Note that doing a remake with reprintfns = NIL makes sense if there have ocen changes in the file, but not to any of- 


the functions, с.р., changes to vars or property lists. 
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printfns[x;-] 


printdate[file;changes] 


filecreated[x] 


prettyheader 


filedate[file] 


prettycomprint[x] 


printdeffexpr:left;def;tailflg:-] 
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highest number) of prttyfile, the second argument to prettydef. If 
sourcefile cannot be found, prettydef prints the message "file 
NOT FOUND, SO IT WILL BE WRITTEN ANEW", and proceeds 
as it does when reprintfns and sourcefile are both NIL. 


x is a list of functions. printfns prints defineq and prettyprints the 
functions to primary output file using primary readtable. Used by 
prettydef, 1.с., command (FNS * FOO) is equivalent to command 
(E (PRINTFNS ЕОО)). 


prints the filecreated expression at beginning of prettydef files. 
changes is for use by the file package. 


Nlambda function. Prints a message (using lispxprint) followed by 
the time and date the file was made, which is car[x]. The message 
is the value of prettyheader, initially "FILE CREATED". If 
prettyheader = NIL, nothing is printed. cdr[x] contains information 


.about the file, e.g., full name, address of file map, list of changed 


items, etc. filecreated also stores the time and date the file was 
made on the property list of the file under the property 
FILEDATES and performs other initialization for the file package. 


value is message printed by filecreated. prettyheader is initially 


"FILE CREATED". If prettyheader=NIL, neither filecreated nor - | 


prettycomprint will print anything. Thus, setting prettyheader - о. 


NIL will result in "silent loads". For example, prettyheader is reset 
to NIL during greeting (Section 22). | 


returns the file date of file, ie. the date contained in the 


FILECREATED expression. 
prints x using lispxprint, unless value of prettyheader — NI L. 


prints the expression ex xpr in a pretty format on the primary output 
file using the primary readtable. left is the left hand тап 
(linclength determines the right hand тагріп.)206 


def=T means expr is a function definition, or a piece of one, i.e., 
prettyprint is essentially printdef[gcetd[fn]:NIL; T]. If def=NIL, по 
special action will be taken for LAMBDA's, PROG's, COND's, 
comments, CLISP, etc. def 15 NIL when prettydef calls prettyprint 


printdef initially performs (TAB LEFT T), which means to space to position left, unless already beyond this position, 


in which case do nothing. 
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to print variables and roper lists, and when printdef is called 
from the editor via the command PPV. | 


tailflg — T means ех рг | ds a tail of a list, and is printed without 
parentheses. 


prints the comment 1. commentl is a separate function to permit 


the user to intercept the printing of comments, perform some 


operation, e.g., reset the line length, print the comment himself, and | 


then restore the line length. For example, this could be 
accomplished by adding (* LAMBDA (X) (RESETFORM | 
(LINELENGTH 100) (COMMENT1 X))) to prettyprintmacros | 
(page 14.49), | | mE 


a commentl is an entry to the prettyprint block. However, it is called internally by prettyprint 50 that advising or 
redefining it will not affect the action of prettyprint. comment] should лог be called when not under a printdef. 
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SECTION 15 
DEBUGGING - THE BREAK PACKAGE! 


15.1 DEBUGGING FACILITIES 


Debugging a collection of LISP functions involves isolating problems within particular functions 
and/or determining when and where incorrect data are being generated and transmitted. In the 
Interlisp system, there are three facilities which allow the user to (temporarily) modify selected 
function definitions so that he can follow the flow of control in his programs, and obtain this 
debugging information. These three facilities together are called the break package. All three 
redefine functions in terms of a system function, breakl са below. 


Break modifies the definition of its argument, a function fn? so ‘that if a break condition (defined 


by the user) is satisfied, the process is halted temporarily on a call to fn. The user can then 
interrogate the state of the machine, perform any computation, and continue or return from the 


call. 


Trace modifies a definition of a function fn so that whenever fn is called, its arguments (or some 
other values specified by the user) are printed. When the value of fn is computed it is printed 
also. (trace is a special case of break). 


Breakin allows the user to insert a breakpoint inside an expression defining a function. When the 
breakpoint is reached and if a break condition (defined by the user) is satisfied, a temporary halt 
occurs and the user can again investigate the state of the computation. 


The following two examples illustrate these facilities. In the first example, the user traces the 
function factorial. trace redefines factorial so that it calls breakl in such a way that it prints some 
information, in this case the arguments and value of factorial, and then goes on with the 


computation. When an error occurs on the fifth recursion, break] reverts to interactive mode, and 
a full break occurs. The situation is then the same as though the user had originally performed · 


BREAK( FACTORIAL) instead of TRACE( FACTORIAL), and the user can evaluate various 
Interlisp forms and direct the course of the computation. In this case, the user examines the 
variable n, and instructs breakl to return 1 as the value of this cell to factorial. The rest of the 
tracing proceeds without incident. The user would then presumably edit factorial to change L to 1. 


The break package was written by W. Teitelman. 

break and trace can also be used on clisp operators (Section 23) which appear as car of form, eg. FETCH, 
REPLACE, IF, FOR, DO, etc, even though these are not implemented as functions. For conditional breaking, the 
user can refer to the entire expression via the variable exp, e.g. BREAK ((FOR (MEMB 'UNTIL EXP) )). 
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Section 15: The Break Package 


In the second example, the user has constructed a non-recursive definition of factorial. He uses 
breakin to insert а call to breakl just after the PROG label LOOP. This break is to occur only on 
= the last two iterations, i.e., when n is less than 2. When the break occurs, the user looks at the 
value of n. mistakenly typing NN. However, the break is maintained and no damage is done. 
After examining n and m the user allows the computation to continue by typing OK. A second 
break occurs аћег the next iteration, this time with N=0. When this break is released, the function | 
factorial returns its value of 120. 


РР FACTORIAL 


(FACTORIAL | 
= [LAMBDA (М) 
(COND | 
((ZEROP N 
L) 
(T (ITIMES N (FACTORIAL (SUB1 №) 
FACTORIAL 
«TRACE ( FACTORIAL) 
(FACTORIAL) | 
СЕАСТОВТА! (4) 


FACTORIAL: 
N= 4 


FACTORIAL: 
N= 3 


FACTORIAL: 
N= 2. 


| FACTORIAL: 
Per 


FACTORIAL: 
N = 0 


U.B.A. 
Een Тш | 
(FACTORIAL BROKEN) 
2% | 
0 
:RETURN 1 
FACTORIAL = 1 
FACTORIAL = 1 
FACTORIAL = 2 
FACTORIAL = 6 
FACTORIAL = 24 
24 
+ 
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«РР FACTORIAL 


(FACTORIAL 
[LAMBDA (М) 
(PROG ((M 1)) 
- LOOP(COND | 
( (7ЕВОР М) | 
(RETURN M))) | 
(ФЕТО M (ІТІМЕ5 M N)) | 
(5ЕТ0 М (SUB1 М)) 
(60 100Р1) | | | 
FACTORIAL то ем | на 
«ВВЕАКТМ( FACTORIAL (AFTER LOOP) (ILESSP М 2] 
SEARCHING... Жағаға 
FACTORIAL 
<ЕДСТОВТА (5). 


((FACTORIAL) BROKEN) 
: ММ | | 


U.B.A. 

NN | | 
(FACTORIAL BROKEN AFTER LOOP) 
:N | 

1 

СМ 

120 


(FACTORIAL) 
(( FACTORIAL) BROKEN) 
:N 


0 

:OK 

( FACTORIAL) 
120 


є 


15.2 ВВЕАК1 


The basic function of the break package is breakl. Whenever Interlisp types а message of the - 
form (- BROKEN) followed by ":" the user is then "talking to" breakl, and we say he is “in a 

break." break] allows the user to interrogate the state of the world and affect the course of the 
computation. It uses the prompt character ":" to indicate it is ready to accept input(s), in the same 
way as evalgt uses "е". The user can type in one of the commands specifically recognized by 
brcakl described below, and the command will be processed, and then another : will be printed, to 
indicate that breakl is ready for more input? Or, the user may type in an expression for 
evaluation, and the value will be printed. The user can even type in commands to the 
programmer’s assistant (Section 22), e.g. to redo or undo previously executed events, including 


break commands. 


unless of course the command caused the break to be exited. 


In fact, all inputs not recognized by breakl are simply passed on to the programmer's assistant. 
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Since breakl puts all of the power of Interlisp at the user’s command, he can do anything he can 
do at evalgt. For example, he can insert new breaks on subordinate functions ampi by typing: 


(BREAK fnl fn2 ...) 
or he can remove old breaks and traces if too much information is being supplied: 


(UNBREAK fn3 fn4 ...) 


He can edit functions, including the one currently broken: 


EDITF(fn) 


For example, the user might evaluate an expression, see that the value was incorrect, call the 


editor, change the function, and evaluate the expression again, al without leaving the break. 


Similarly, the user can prettyprint fractious define new functions or г redefine old ones, load : a “file, 
compile functions, time a computation, etc. In short, anything that he can do at the top level can 


^. be done while inside of the break. In addition the user can examine the pushdown list, via the 


_ functions described in Section 12, and even force a return. back. to some- higher function via the 
г function retfrom or reteval. | 


It is important to emphasize that once a break occurs, the user is in complete бг of the flow of 
the computation, and the computation will not proceed without specific instruction from him. If 


the user types in an expression whose evaluation causes an error, the break is maintained. 


^ Similarly if the user aborts a computation? initiated from within the break, the break is maintained. 


+++ 


_ Only if the user gives one of the commands that exits from the break, or evaluates a form which 
_ does a retfrom Or reteval back out of break], will the computation continue. | 


| Note that break] 15 just another Interlisp function, not a special system feature like the шерге | 
_ ог the garbage заре collector. It has arguments which are explained later, and returns a value, the same 


as cons or cond or prog or any other function.’ The value returned by break] is called "the value 
of the break." The user can specify this value explicitly by using the RETURN command described | 
below. But in most cases, the value of a break is given implicitly, via a GO or OK command, and is 
the result of evaluating "the break expression," brkexp, which is one of the arguments to breakl. 


The break expression is an expression equivalent to the computation that would have taken place 


. . had no break occurred. For example, if the user breaks on the function FOO, the break expression 
15 the body of the definition of FOO. When the user types OK or GO, the body of FOO is 
evaluated, and its value returned as the value of the break, i.e., to whatever function called FOO. _ 


The effect is the same as though no break had occurred. In other words, one can think of break] | 


5 |... By typing control-E, see Section 16. 

6 Except that breakl does not "turn off" control-D, i.e., a control- D will force an immediate return back to the top ши 
level. | | | 

7 Furthermore, since break] itself calls functions, when one of these is broken, an infinite loop would occur, break} 


detects this situation, and prints Break within a break on and the name of the function, and then simply calls - 
the function without going into a break. 
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Breakl 


as а Бај eval, which permits interaction before and after evaluation. The break expression then - 
corresponds to- to the argument to eval. | 


ВВЕАК ышы 


60 Releases the break and allows the computation to proceed.’ бгеак1 
| evaluates brkexp, its first argument, prints the value of the break. 
brkexp is set up by the function that created Ше call to breakl. 
For break or trace, brkexp is equivalent to the body ‘of the 
definition of the broken function. For breakin, using BEFORE or 
AFTER, brkexp is NIL. For breakin AROUND, brkexp is the 
indicated expression. See breakin, page 15.16. = | | 


OK | Same as GO except the value of brkexp is not printed. 


EVAL Same as GO or OK except that the break is maintained after the 


evaluation. The user can then interrogate the value of the break 
which is bound on the variable !value, and continue with the break. 
Typing GO or OK following EVAL will not cause reevaluation but 
another EVAL will. EVAL is a useful command when the user is 
not sure whether or not the break will produce the correct value 
and wishes to be able to do something about it if it is wrong. 


RETURN form 
or a | 

RETURN fn[args] The value of the indicated computation is returned as the value of 
the break. For example, one might use the EVAL command and 
follow this with RETURN (REVERSE !VALUE). 

t Calls error! and aborts the break. i.e., makes it "ро away" without 
returning a value. This is a useful way to unwind to a higher level 
break. All other errors, including those encountered while 
executing the GO, OK, EVAL, and RETURN commands, maintain 
the break. 

I EVAL function is first unbroken, then the break expression is evaluated, 
and then the function is rebroken. Very useful for dealing with 
recursive functions. | 

10K Function is first unbroken, evaluated, rebroken, and then exited, 
i.e, І ОК is equivalent to | EVAL followed by ОК. 

8 


In order to facilitate debugging of programs that perform input operations, the carriage return that is typed to 
complete the GO, OK, EVAL, ctc. commands is discarded, i.e., read by bre breakl, so that it will not be pate of the 
input stream. 
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Function is first unbroken, evaluated, rebroken, and exited with 
value typed, i.e., ! EVAL followed by GO. 


unbreaks brkfn, e.g., | 


(FOO BROKEN). 
: UB 


го 


and 200 is now unbroken 


resets the variable lastpos, which establishes a context for the 
commands ?=, ARGS, BT, BTV, BTV*, and EDIT, and IN? 
described below. lastpos is the position of a function call on the 
push-down stack. It is initialized (60 the function just Delors, the call. 
to breakl, i.e., stknth[-1;BREAK1)? | | 


@ treats the rest of the teletype line as its argument(s). It first 
resets lastpos to stknth[-1;BREAK1] and then for each atom on the | 
line, @ searches backward, for a call to that atom. The following 
atoms are treated Specially: | 


@ do not reset lastpos to stknth[-1;BREAK 1] but: leave it 
| as it was, and continue searching from that point. 


numbers if negative, move lastpos back that number of calls, if - 


positive, forward, i.e., reset lastpos to stknth[n;lastpos]. ша 


/ _ the next atom is a number and can be used to specify 
more than one call е.р., | 
@ FOO / 3 is equivalent to 
@ FOO FOO FOO 


= resets lastpos to the value of the next expression, e.g., 
if the value of FOO is a stack pointer, @ = FOO ЕТЕ 
will search for FIE in the environment ра бу 

(the value of) FOO. 


. When control passes from break], e.g. as a result of an EVAL, OK, GO, REVERT, т command, or via а RETFROM or 
RETEVAL typed in by the user, (RELSTK LASTPOS) is executed to release this stack pointer. | 
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. Example: 
If the push-down stack looks like 


BREAK1 (13) 


ЕОО (12) 
ФЕТО | а) 
COND (10) 
PROG (9) 
FIE (8). 
COND ^ (7) 
ЕТЕ (6) 
COND . (5) 
'FIE (4) 
COND (3) 
PRG D? 
FUM (1) 


then @ FIE COND will set lastpos to the position corresponding to 
(7); @ @ COND will then set lastpos to (5); and @ ЕТЕ / 3 -1 to 
(3). 


If @ cannot successfully complete a search, it searches the stack- 
again from that point looking for a call to a function whose name is 
close to that of fn, in the sense of the spelling corrector (Section 
17), where fn is the name of the function for which it was 
searching. If the search is still unsuccessful, (0 types 
(fn NOT FOUND), and then aborts. | 


+ + + + 


When @ finishes, it types the name of the function at lastpos, i.e., 
stkname[lastpos] 


@ can be used on brkcoms. In this case, the next command on © 
brkcoms is treated the same as the rest of the teletype line. 


I= This is a multi-purpose command. Its most common use is to 
interrogate the value(s) of the arguments of the broken function, 
e.g, if FOO has three arguments (X У Z), then typing ?- to a 
break on FOO, will produce: 


= 

X = value of X 
ya value of Y 
= value of Z 


10 


In fact, = is a universal mnemonic for displaying argument names and their corresponding values. In addition to 
being a break command, ?— is an edit macro which prints the argument names and values for the current expression 
(see Section 9), and a read-macro (actually ? is the read-macro character) which docs the same for the current level 
list being read (see Sections 2 and 22). | 
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Section 15: Тһе Break Package | 


= operates on the rest of the teletype line as its arguments. If the 
line is empty, as in the above case, it operates on all of the 
arguments of the broken function. If the user types 
?= X (САВ Y), he will see the value!! of X, and the value of 
(CAR Y). The difference between using ?= and typing X and 
(CAR Y) directly to breakl is that ?= evaluates its inputs as of 
lastpos, i.e., it uses stkeval. This provides a way of examing 
variables or performing computations as of a particular point on 
the stack. For example, @ FOO / 2 followed by ?= X will allow — 
the user to examine the value of X in the previous call to ЕОО, etc. 


?- also recognizes numbers as refering to the correspondingly 
numbered argument, i.e., it uses stkarg in this case. Thus 


:@ ЕТЕ 

FIE 

:?= 2 

will print the name and value of the second argument of FI E. | 


?— can also be used on brkcoms, in which case the next command . 


. on brkcoms is treated as the rest of the teletype line. For example, 


if brkcoms is (EVAL ?= (X Y) GO), brkexp will be evaluated, 
the values of X and Y printed, and then the function exited with its 
value being printed. 


(print bindings) like ?— except ascends the stack starting from 
lastpos, and, for each frame in which the given variable is bound, 
prints the frame name and value of the variable (with printlevel 
reset to (2. 3), e.g. 


:PB FOO | 
8 FN1/*PROG*LAM: 3 


@ FN2: 10 


8 ТОР: NOBIND 


.. Prints a backtrace of function names only starting at lastpos. (See 


discussion of @ above) The several nested calls in system packages 
such as break, edit, and the top level executive appear as the single - 
entries **BREAK**, **EDITOR**, and **TOp** кошо; 


The value of each variable is printed with the function showprint (Section 14), so that if sysprettyflg — T, the value 
will be prettyprinted. 


PB is also a programmer's assistant command (Section 22), so that it can also be typed in when talking to the 
programmer's assistant, but. not in a break. PB is implemented via the function printbindings. 


The value of breakdelimiter is what is printed to delimit the output of ?= and backtrace commands. Initially "2" 
but can be resct, e.g. to ",", for more linear output. - 
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BTV 


BTV+ 


BTV* 


BTV! 


BT, 
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Prints a backtrace of function names with variables beginning at 
lastpos. | 


Same as BTV except also prints localvars and arguments to subrs. | 


пе Section xd 


Same as BTV except prints arguments to subrs, localvars, and 
pora of the аны i.e. eval blips (see Section 12). 


Same as BTV except prints everything on stack (see Section 12). 


BTV, BTV+, BTV*, and BTV! all permit an optional functional argument which is a 
predicate that chooses functions to be skipped on the backtrace, е.р., BT SUBRP will skip ай 
SUBRs, BTV (LAMBDA (X) (NOT (MEMB X FOOFNS))) will skip all but those functions on 
FOOFNS. If used as a brkcom the functional argument is no longer optional, 1.е., the next brkcom 
must either be the functional argument, or NIL if no functional argument is to be applied. 


For BT, BTV, BTV+, BTV*, and BTV!, if control-P is used to change a printlevel during Ше 
backtrace, the printlevel will be restored after the backtrace is completed. | 


ARGS 


Prints Ше names of the variables bound at lastpos, ie., 


variables[lastpos] (Section 12). For most cases, these аге (ће | 


arguments to the function entered а that position, і.е., 


. arglist[stkname[lastpos]]. 


The following two commands are for use only. with unbound atoms or undefined function breaks 
(see Section 16). | | 


= form 


14 


= fn[args] 


only for (ће break following an unbound atom error. Sets the atom 
to the value of the form, or function and arguments, exits from the 
break returning that value, and continues the computation, e.g., 


Џ.В.А. 
(FOO BROKEN) 
= (COPY FIE) 


sets FOO and goes on. 


The value of each variable is printed with the function showprint сен 14), : so that if sysprettylg=T, Ше value 
will be prettyprinted. | . 
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for use either with unbound atom error, or undefined function | 
error. Replaces the expression containing the error with е expr! > (not 


the value of e expr) e.g., 


U.D.F. | 
(2001 BROKEN) - 
:-» FOO 


к changes the F F001 to F 00 and c continues the computation. 


| схрг need not Бе atomic, е. ga a 


U.B.A. 
(FOO BROKEN) | 
:-> (QUOTE FOO) 


. For U.D. F. breaks, the. user can specify a function and initial 00 
arguments, ед RN : | га 


0.0.Ғ. 


^. (MEMBERX BROKEN) 
ЕЕ А MEMBER X | 


| Note that in the case of a Џ. D. F. error occurring mediately. ры 
22 following а сай to a арріу, e.g, (APPLY X Y) where the value of x- 
= is FOO and FOO is undefined, or a U.B.A. error immediately - 
- following a call to eval, e.g., (EVAL X), where the value of x 5 
РОО and FOO is unbound, there is no expression containing the 
22-2 offending atom. In this case, - ? cannot operate, so 1 5 printed | 
апі no action taken. | 


|... designed fof uie dn. conjunction with breaks caused зу ‘errors. 
p Facilitates editing the expression causing the break: 


О NON-NUMERIC ARG 
NIL 
(IPLUS BROKEN) 
EDIT 00 
14 FOO. 
— (IPLUS X 1). 


EDIT 


| “а ү) 


*OK 


and user can continue by typing OK, EVAL, etc. 


-> does not change just bikerp: it changes the function or expression containing the erroneous form. In other _ 


2 мога, the user docs not have to perform any additional noe 
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This command is very simple conceptually, but complicated in its implementation by all of the 


exceptional cases involving interactions with compiled functions, breaks on user functions, error 


. breaks, breaks within breaks, et al. Therefore, we shall give the following simplified explanation 
which will account for 90% of the situations arising in actual usage. For those others, EDIT will 
print an appropriate failure message and return to the break. 


EDIT begins by searching up the stack beginning at lastpos (set by @ command, initially position 
of the break) looking for a form, i.e., an internal call to eval. Then EDIT continues from that 
point looking for a call to an interpreted function, or to eval. It then calls the editor on either the 
EXPR or the argument to eval in such a way as to look for an expression eq to the form that it 
first found. It then prints the form, and permits interactive editing to begin. Note that the user 
can then type successive 0’s to the editor to see the chain of superforms for this computation. 


If the user exits from the edit with an OK; the break expression is reset, if possible, so that the 
user can continue with the computation by simply typing OK.16 However, in some situations, the 
break expression cannot be reset. For example, if a compiled function ЕОО incorrectly called putd 
and caused the error ARG NOT ATOM followed by a break on putd, EDIT might be able to find 
the form headed by FOO, and also find that form in some higher interpreted function. But after 
the user corrected the problem in the FOO-form, if any, he would still not have in any way 
informed EDIT what to do about the immediate problem, i.e., the incorrect call to putd. However, 
if FOO were interpreted EDIT would find the putd form itself, so that when the user corrected that 
form, EDIT could use the new corrected form to reset the break expression. The two cases are 
shown below: 


ARG МОТ АТОМ ARG NOT ATOM 
( FUM) (PUTD BROKEN) 
(PUTD BROKEN) | : EDIT 
: EDIT IN РОО... 
IN FIE... | (PUTD X) 
(FOO X) | EDIT 
EDIT | "(2 (CAR X)) 
*(2 (CAR X)) *OK | 
*OK | ЕОО 
NOTE: BRKEXP МОТ CHANGED : ОК 
ЕТЕ РИТО 
:?= 
Џ = (ЕШМ) 
:($ЕТО Џ (САВ Џ)) 
ЕЏМ 
: ОК 
РИТО 
IN? similar to EDIT, but just prints parent form, and superform, but 


does not call editor, e.g., 


ATTEMPT TO RPLAC NIL 
Т 

(RPLACD BROKEN) 

: IN? 


16 Evaluating the new brkexp will involve recvaluating the form that causes the break, e.g., if (PUTD (QUOTE (F00)) 


big-computation) were handled by EDIT, big-computation would be reevaluated. 
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FOO: (RPLACD X 7) 


Although EDIT and IN? were designed for error breaks, they can also be useful for user breaks. 
For example, if upon reaching a break on his function FOO, the user determines that there is a 
problem in the сай to FOO, he can edit the calling form and reset the break expression with one 
operation by using. EDIT. The following two protocol's. with and without the use of EDIT, 
illustrate this: 


(FOO BROKEN) (ЕОО BROKEN) 
:?= :?= 
Х = (АВ С) Х = (АВ С) 
У =» 0 Ү = р. 
: В | : EDIT 
IN FIE... 
Ғ00 | (FOO V U). 
5ЕТ0 EDIT 
COND __ find which function *(SW 23) 
PROG FOO is called from *OK 
FIE | | ЕТЕ М 
| (aborted with ТЕ) . :0K 
: EDITF(FIE) ЕОО 
EDIT | | 
*F FOO P 
(FOO VU) ейи 
"(54 2 3) 
“ОК 
ҒІЕ 
:(SETQ Y X) reset X and Y 
(A B C) 
:(SETQQ X D) 
D 
:?= 
X=D 
У = (АВ С) check them 
:OK | 
Ғ00 


REVERT goes back to position lastpos on stack and reenters the function 
| | called at that point with the arguments- found on the stack.!® If the 
function is not already broken, REVERT first breaks it, and then 

unbreaks it after it is reentered. 


REVERT is useful for restarting a computation in the situation where a bug is discovered at some 
point below where the problem actually occurred. REVERT essentially says "ро back there and start 
over in a break." 


17 x and y have not been changed, but brkexp has. See previous footnote, 


B REVERT can also be given the position using the conventions described for @ on page 15.6, е.р., REVERT ЕОО -1 
| is equivalent to 9 FOO -1 followed by REVERT. 
» REVERT will work correctly if the names or arguments to the function, or even its function type, have been changed. 
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Break Commands 


ORIGINAL for use in conjunction with breakmacros (described below). Form 
is (ORIGINAL . COMS). coms are executed without regard for 
breakmacros. Useful for redefining а break command in terms of 
itself. 


BRKCOMS 


The fourth argument to breakl is brkcoms, a list of break commands that breakl interprets and 
executes as though they were teletype input. One can think of brkcoms as another input file which 
always has priority over the teletype. Whenever bikcoms-— NIL, breakl reads its next command 
from the teletype. Whenever brkcoms is not NIL, breakl takes as its next command car[brkcoms] 
and sets brkcoms to cdr[brkcoms].? For example, suppose the user wished to see the value of the 
variable x after a function was evaluated. Не would set up а break with 
brkcoms— (EVAL (PRINT X) OK), which would have the desired effect. The function trace uses 
brkcoms: it sets up a break with two commands; the first one prints the arguments of the function, 
or whatever the user specifies, and the second is the command GO, which causes the function to be 
evaluated and its value printed. 


If brkcoms is not NIL, the value of a break command is not printed. If you desire to see a value, 
you must print it yourself, as in the above example with the command (PRINT X). 


Note: whenever an error occurs, brkcoms is set to NIL, and a full interactive break occurs. 


BRKFILE 


The break package has a facility for redirecting ouput to a file. The variable brkfile should be set 
to the name of the file, and the file must be opened. All output resulting from brkcoms will be 
output to brkfile, е.р., output due to TRACE. Output due to user typein is not affected, and will 
always go to the terminal. brkfile is initially T. 


BREAKMACROS 


Whenever an atomic command is given breakl it first searches the list breakmacros for the 
command. The form of breakmacros is ( ... (macro command, command, .. . command, . .. If 
the command is defined as a macro, break] simply appends its definition, which is a sequence of 
break commands, to the front of brkcoms, and goes on. If the command is not contained in 
breakmacros, break] then checks to see if it is one of the built in commands, and finally, treats it 
as a function or variable as before?! 


20 Normally, when a user breaks or traces a function, the value of brkcoms for the corresponding call to break] will be 
defaulted to NIL. However, it is possible to specify a list of break commands, as described in the discussion of break 
and breakl below. 

21 


If the command is not the name of a defined function, bound variable, or lispx command, break] will attempt 
spelling correction using brcakcomslst as a spelling list. If spelling correction is unsuccessful, ше. will go ahead 
and call lispx anyway, since the atom may also be a misspelled history command, 
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Example: the command ARGS could be defined by including оп  breakmacros: 
(ARGS (PRENT (VARIABLES LASTPOS T))) | 


BREAKRESETFORMS 


If the user is developing programs that change the way a user and Interlisp normally interact, е.р., 
change or disable the interrupt or line-editing characters, turn off echoing, etc., debugging them by. 
breaking or tracing may be difficult, because Interlisp might be in a “funny” state at the time of 
the break. breakresetforms is designed to solve this problem. The user puts on breakresetforms 
expressions suitable for use in conjunction with resetform or, resetsave (section 5).2 22 When a break 
occurs, breakl evaluates each expression on breakresetforms before any interaction with the 
terminal, and saves the values. When the break expression is evaluated via an EVAL, OK, or GO, 
breakl first restores Ше state of the system with respect to the various expressions on 
breakresetforms. When (if) control fetums to breakl, the expressions on breakresetforms are again 
evaluated, and their values saved.2? When the break is exited ма an OK, GO, RETURN, ог + 
command, or via a RETFROM or RETEVAL typed in by the user24 break] again restores] state. 
Thus the net effect is to make the break invisible with respect to the user’s programs, but 
nevertheless allow the user to interact in the break in the normal fashion. 


15.3 BREAK FUNCTIONS 


Ъгеак [brkexp: brkwhen;brkfn;brkcoms; -brktype] 

is an nlambda. brkwhen determines whether a break is to occur. 
If its value is NIL, brkexp is evaluated and returned as the value of 
breakl. Otherwise a break occurs and an identifying message is- 

printed using brkfn. Commands are then taken from brkcoms or 
the teletype and interpreted. Тһе commands, GO, 160, OK, 
IOK, RETURN and 7, are the only ways to leave breakl. Тһе 
command EVAL causes brkexp to be evaluated, and saves the value 
on the variable !value. Other commands can be defined for Бгеак1 
via breakmacros. brktype is NIL for user breaks, INTERRUPT for 
control-H breaks, and ERRORX for error breaks. 


For error breaks, the input buffer is cleared and saved. (For control-H breaks, the input buffer 
was cleared at the time the control-H was typed, see Section 16.) In both cases, if the break returns 
a value, i.e., is not aborted via t or control-D, the input buffer will be restored (see Section 14). 


22 e.g, (ECHOMODE T), (CONTROL), etc., i.e., the value of each form is its “previous state," so that the effect of 
evaluating the form can be undone by applying car of the form to the value. setq expressions can also be included 
on  breakresetforms for saving апа restoring system parameters, eg. (SETQ LISPXHISTORY NIL), 
(ФЕТО DWIMFLG NIL), etc. These are handled specially by Бгеак1 in that the current value of the variable is saved 
before the setq is executed, and upon restoration, the variable is set back to this value. 


23 The state of the system is also restored if the user types control-D. 
24 All user type-in is scanned in order to make the operations undoable as described in section 22. At this point, 


RETFROMs and RETEVALs are also noticed. However, if the user types in an expression which calls a function that 
then does a RETFROM, this RETFROM will not be noticed, and the effects of breakresetforms will not be reversed. 


25 As mentioned earlier break1 detects "Break within a break" situations, and avoids infinite loops. If the loop occurs 


because of an error, break] simply rebinds breakresctforms to NIL, and calls help. This situation most Hoquenty 
occurs when there is a bug in a function called by breakresetforms. 
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breakO[fn;when;coms;-;-] 
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Break Functions 


sets up a break on the function #126 by redefining fn as a call to 
breakl with brkexp an equivalent definition of fn, and when, fn, 
and coms, as brkwhen, brkfn, brkcoms. Puts property BROKEN on 
property list of fn with value a gensym defined with the original 
definition. Puts property BRKINFO on property list of fn with 
value (BREAKO when coms) (For use in conjunction with rebreak). 
Adds fn to the front of the list brokenfns. Value is fn. 


If fn is not defined, returns (fn NOT DEFINED). 


If fn is non-atomic and of the form (fal IN fn2), breakO first calls a 
function which changes the name of fnl wherever it appears inside 
of fn2 to that of a new function, fnl-IN-fn2, which it initially 
defines as fnl. Then breakO proceeds to break on fnl-IN-fn2 
exactly as described above. This procedure is useful for breaking 
on a function that is called from many places, but where one is 
only interested in the call from а specific function, e.g. 
(RPLACA IN FOO), (PRINT IN ЕТЕ), etc. It is similar to 
breakin described below, but can be performed even when FN2 is 
compiled or blockcompiled, whereas breakin only works on 
interpreted functions. | 


If fnl is not found іп fn2, break0 returns Ше value 
(ба1 NOT FOUND ІМ #2). | | 


If fnl is found in fn2, in addition to breaking fnl-IN-fn2 and 
adding fnl-IN-fn2 to the list brokenfns, break0 adds fnl to Ше 
property value for the property NAMESCHANGED on the property 
list of fn2 and adds the property ALIAS with the value (fn2 . fnl) 
to the property list of fnl-IN-fn2. This will enable unbreak to 


recognize what changes have been made and restore the function 


fn2 to its original state. 


If fn is nonatomic and not of the above form, break0 is called for 


each member of fn using the same values for when, coms, and file 
specified in this call to breakO. This distributivity permits the user 
to specify complicated break conditions on several functions without 
excessive retyping, e.g., 


ргеакОГ(ЕОО1 ((PRINT PRIN1) IN (F002 F003))); 
(МЕО X T);(EVAL ?- (Y 2) OK)] 


will break on F001, PRINT-IN-FOO2, PRINT-IN-FOOS, 
PRIN1-IN-FO002 and PRIN1-IN-FO003. 


If fn is non-atomic, the value of breakO is а list of the individual 
values. 


As mentioncd carlicr, it is also possible to break on clisp operators that appear as car of a form, ер IF, FETCH, 


REPLACE, 


FOR, DO, etc. 
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· break[x] | is а nospread nlambda. For each atomic argument, it performs 

| breakO[atom;T]. For each list, it performs apply[BREAKO;list]. For 
example, break[FOO1 (F002 (GREATERP М 5) (EVAL))] is 
equivalent to breakO[FO01,T] and 
breakO[FOO2; (GREATERP М 5); (EVAL)] 


trace[x] is a nospread nlambda. For each atomic argument, it performs 
- breakO[atom;T ; (TRACE ?= NIL 60) 127 For each list argument, 
car is the function to be traced, and cdr the forms the user wishes 

to see, 1.е., trace performs: 


breakO[car[list];T;list[T RACE;? =; cdr[list],GO]] 


For example, TRACE(FOO1 (F002 Y)) will cause both F001 and 
2002 to be traced. АП the arguments of F001 will be printed; 
only the value of Y will be printed for Ғ002. In the special case 
that the user wants to see only the value, he can perform 
TRACE((fn). This sets up а break with commands 
(TRACE ?= (NIL) GO). 


Note: the user can always call break0 himself to obtain combination of options of breakl not 
directly available with break and trace. These two functions merely provide convenient ways of 
calling break0, and will serve for most uses. 


BREAKIN 


Breakin enables the user to insert a break, ie. a call to breakl, at a specified location in an 
interpreted function. For example, if foo calls fie, inserting a break in foo before the call to fie is 
similar to breaking fie. However, breakin can be used to insert breaks before or after prog labels, 
particular SETQ expressions, or even the evaluation of a variable. This is because breakin operates 
by calling the editor and actually inserting a call to breakl at a specified point inside of the 
function. 


The user specifies where the break is to be inserted by a sequence of editor commands. "These 
commands are preceded by BEFORE, AFTER, or AROUND, which breakin uses to determine what 
to do once the editor has found the specified point, i.e., put the call to breakl BEFORE that point, 
AFTER that point, or AROUND that point. For example, (BEFORE COND) will insert a break 
before the first occurrence of cond, (AFTER COND 2 1) will insert a break after the predicate in 
the first cond clause, (AFTER ВЕ (SETQ X &)) after the /ast place X is set. Note that 
(BEFORE TTY:) or (AFTER TTY:) permit the user to type in commands to the editor, locate 
the correct point, and verify it for himself using the P command if he desires, and exit from the 
editor with ОК.28 breakin then inserts the break BEFORE, AFTER, or AROUND that point. 


27 The Пар TRACE is checked for in breakl and causes the message "function :" to be printed instead of (function 


BROKEN). 
% д STOP command typed to TTY: produces the same effect as an unsuccessful edit command in the original 
specification, е.р., (BEFORE CONDD). In both cases, the editor aborts, and breakin types (NOT FOUND). 
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For breakin BEFORE or AFTER, the break expression is NIL, since the value of the break is 
irrelevant. For breakin AROUND, the break expression will be the indicated form. In this case, the 
‘user can use the EVAL command to evaluate that form, and examine its value, before allowing the 
computation to proceed. For example, if the user inserted a break after a cond predicate, e.g., 
(AFTER (EQUAL X Y)), he would be powerless to alter the flow of computation if the predicate 
were not true, since the break would not be reached. However, by breaking 
=. (AROUND (EQUAL X Y)), he can evaluate the break expression, i.e., (EQUAL X. Y), look at its 

value, and return something else if he wished. | 


The message typed for a breakin break, is ((fn) BROKEN), where fn is the name of the function | 
inside of which the break was inserted. Any error, or typing control-E, will cause the full 
identifying message to be printed, e.g., (ЕОО BROKEN AFTER COND 2 1). 


А special check is made to avoid inserting а "break inside of an expression headed by any member 
of the list nobreaks, initialized to (GO QUOTE *), since this break would never be activated. For 
example, if (GO L) appears before the label L, breakin (AFTER L) will not insert the break 
inside of the GO expression, but skip this occurrence of L and go on to the next L, in this case the 
label L. Similarly, for BEFORE or AFTER breaks, breakin checks to make sure that the break is 
being inserted at a "safe" place. For example, if the user requests a break (AFTER X) in 
(PROG -- (SETQ X &) --), the break will actually be inserted AFTER (SETQ X &), anos a 

message printed to this effect, e.g; BREAK INSERTED AFTER (SETQ X 4). | 


breakin[fn;where;when;coms] breakin is an nlambda. when and coms are similar to when and 
coms for break0, except that if when is NIL, T is used. where 
specifies where in the definition of fn the call to breakl is to be 
inserted. (See earlier discussion). 


If fn is a compiled function, breakin returns (fn UNBREAKABLE) as 
its value. 


If fn is interpreted, breakin types SEARCHING... while it calls the 
editor. If the location specified by where is not found, breakin 
types (NOT FOUND) and exits. If it is found, breakin adds the 
property BROKEN-IN with value T, and the property BRKINFO 
with value (where when coms) to the property list of fn, and adds 
fn to the front of the list brokenfns. 


Multiple break points, can be inserted with a single call to breakin 
by using a list of the form 
((BEFORE ...) .. (AROUND ...)) for where. It is also 
possible to call break or trace on a function which has been 
modified by breakin, and conversely to breakin a function which 
has been redefined by a call to break or trace. 


unbreak{x] unbreak is a nospread nlambda. It takes an indcfinite number of 
functions modified by break, trace, or breakin and restores them to 
their original state by calling unbrcak0. Value is list of values of 
ипбгсако, 


unbrcak[] will unbreak ай functions оп brokenfns, in reverse order. 
It first scts brkinfolst to NIL. | 
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 unbreakO[fn;-] 


unbreakin[fn] 


rebreak[x] 


breakread[type] | 


changename[fn; from;to] 
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unbreak[T | unbreaks just the first function on brokenfns, i.e., the 
most recently broken function. 


 restores fn to its original state. If fn was not broken, value is 


(NOT BROKEN) and no changes are made. If fn was modified by 


breakin, unbreakin is called to edit it back to its original state. If 


fn was created from (fnl IN #02), i.e., if it has a property ALIAS, 
the function in which fn appears is restored to its original state. АП 
dummy functions that were created by the break are eliminated. 


| Adds property value of BRKINFO to (front of) brkinfolst. 


Note: unbreakO[(fnl. IN fn2)] is allowed: unbreakO will operate on 
fnl-IN-fn2 instead. 


performs the appropriate editing operations to eliminate all changes 
made by breakin. fn may be either the name or definition of a 


function. Value is fn.  Unbreakin is automatically called by 


unbreak if fn has property BROKEN-IN with value T on its 
property list. | 


is an nlambda, nospread function for rebreaking functions that were 
previously broken without having to  respecify the break 
information. For each function on x, rebreak searches brkinfolst for 
break(s) and performs the corresponding operation. Value is a list 
of values corresponding to calls to break0 or breakin. If no 
information is found for а particular function, value is 
(fn - NO BREAK INFORMATION SAVED). XE 


тебгеак[] rebreaks everything on brkinfolst, i.e., rebreak[] is the 
inverse of unbreak[]. | 


гергеакГТ | rebreaks just the first break оп brkinfolst, ie. the 
function most recently unbroken. | 


useful for writing breakmacros. If brkcoms is non-NIL (i.e. when 

the command in which the call to breakread appears is part of a list | 
of break commands, rather than having been typed in) returns the 
next break command from the list, which it also sets to its cdr, 
Otherwise, if type =LINE, returns the rest of the commands on the 
line as a list. Otherwise, returns the next command on the line. For 
example, the BT command 15 defined as 
(BAKTRACE LASTPOS NIL (BREAKREAD) 0 T). Thus, if the 


user types BT, the third argument to baktrace will be NIL. If the 


user types ВТ SUBRP, thc third argument will be SUBRP. 


changes all occurrences of from to to in fn. fn may be compiled or 
blockcompiled. Valuc is fn if from was found, otherwise NIL. 
Docs not perform any modifications of property lists. Note that 
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from and to do not have to be functions, e.g., they can be names of 
variables, or any other literals. | 


virginfn[ fn; 12] is the function that knows how to restore functions to their original 
| state regardless of any amount of breaks, breakins, advising, 
compiling and saving exprs, etc. It is used by prettyprint, define, 
and the compiler. If flg=NIL, as for prettyprint, it does not 
modify the definition of fn in the process of producing a "clean" 
version of the definition, i.e., it works on a copy. If flg=T as for 
the compiler and define, it physically restores the function to its 
original state, and prints the changes it is making, e.g. 
РОО UNBROKEN, FOO UNADVISED, FOO NAMES RESTORED, 
etc. Value is the virgin function definition. 


baktracefipos;epos;skipfn;flags] prints backtrace Кош ipos to epos. flags specifies the options of the 
backtrace, ер,  do/don't print arguments, do/don't print 
temporaries or the interpreter, etc., and is the same as for backtrace 
(Section 12)?. baktrace collapses the sequence of several function 
calls corresponding to а call to a system package into a single 
"function" using baktracelst as described below, e.g., any call to the 
editor is printed as **EDITOR**, а break 15 printed as 
**BREAK**, etc. If skipfn is not NIL and skipfn[stkname[pos]] is 
T, pos is skipped (including all variables). baktrace is used by the 
BT, BTV, BTV+, BTV*, and BTV! commands, with flags=0, 1, 
5, 7, and 47Q respectively. | 


baktracelst used for telling baktrace (ie. the BT, BTV, etc. commands) to 
abbreviate various sequences of function calls on the stack by a 
single key, e.g. **BREAK**, **EDITOR**, etc. 


The operation of baktrace and format of baktracelst is described so that the user can add his own 
entries to baktracelst. Each entry on baktracclst is a list of the form (framename key . pattern) or 
(framename (key, . patternj) ... (key, . pattern,)), where a pattern is а list of elements that are 
. either atoms, which match a single frame, or lists, which are interpreted as a list of alternative 
patterns, e.g. (РВОСМ **BREAK** EVAL ((ERRORSET BREAK1A BREAK1) (BREAK1))) 


baktrace operates by scanning up the stack and, at each point, comparing the current frame name, 
with the frame names on baktracelst, i.c. it does an assoc. If the frame name does appear, baktrace 
attempts to match the stack as of that point with (onc of) the patterns. If the match is successful, 
Бак гасе prints the corresponding key, and continues with where the match left off. If the frame 
namc docs not appear, or the match fails, baktrace simply prints the frame name”? and continues 
with the next higher frame. 


29 The call to backtrace specifies that the values of any variables, blips, temporaries, etc. be printed with the function 
showprint (Section 14), so that if sysprettyflg = T, the values will be prettyprinted. 
30 


unless skipfn applied to the frame name is non-NIL as described in discussion Of baktrace, in which case nothing is 
printed. 
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Matching is performed by comparing atoms in the pattern with the current frame name, and 


matching lists as patterns, ie. sequences of function calls, always working up the stack. For 
dap either of the sequence of function calls... BREAK1 BREAK1A ERRORSET EVAL PROGN... 


. BREAK1 EVAL PROGN... would match with the sample entry given above, causing мр 


з ‘be printed. 


Special features: - 


1. Тһе atom & can be used to match any frame. 


2. The pattem "-" сап be used to match nothing. - is useful for specifying an optional match, 
e.g. the example above could also have оеп written as 


(PROGN **BREAK** EVAL ((ERRORSET BREAK1A) -) BREAK1). 


3. Itis not necessary to provide in the pattern for matching dummy frames, i.e. frames for which 


dummyframep (see Section 12) is true, e.g. in Interlisp-10, *PROG*LAM, “ЕМУ”, NOLINKDEF 1, 


etc. When working on a match, the matcher automatically skips over these frames when they do 


not match. 


4. If a match succeeds and the key is NIL, nothing is рока Еог example, (*PROG*LAM NIL 
EVALA “ЕММ)31 


1 This sequence will occur following an error which then causes a break if some of the function's arguments аге 


localvars. 
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SECTION 16 
ERROR HANDLING 


16.1 UNBOUND ATOMS AND UNDEFINED FUNCTIONS 


Whenever the interpreter encounters an atomic form with no binding on the push-down list, and 
whose value cell contains the atom NOBIND,! the interpreter calls the function faulteval. Similarly, 
faulteval is called when a list is encountered, car of which is not the name of a function or a 
function object.) The value returned by faulteval is used by the interpreter exactly as though it 
were the value of the form. | 


faulteval is defined to print either U.B.A., for unbound atom, or U.D.F., for undefined 
function, and then to call breakl giving it the offending form as brkexp.? Once inside the break, 
the user can set the atom, define the function, return a specified value for the form using the 
RETURN command, etc., or abort the break using the * command. If the break is exited with a 
value, the computation will proceed exactly as though no error had occurred. | 


The decision over whether ог not to induce a break depends on the depth of computation, and the 
amount of time invested in the computation. The actual algorithm is described in detail below in 


As described in Section 3, in Interlisp-10, atoms are initialized (when they are created by the read program) without 
value cells. However, from the standpoint of the interpreter, an atom without a value cell is treated the same as an 
atom with a value cell containing NOBIND. The function boundp (Section 3) is available for testing whether or not 
an atom is bound in the sense described above, i.e. boundp[var]=T means that the variable either has a binding, ог 
else has a value in its value cell other than NOBIND. 


2 In Interlisp-10, because of the widespread use of CLISP (Section 23), before calling faulteval, if clisparray is non- 
NIL, the interpreter performs gethash[expression; CLISPARRAY], and if the result is non-NIL, treats it as the new 
expression to be evaluated, and goes on. This avoids going through the faulteval mechanism, and is done purely in 
the interests of efficiency. | 


3 If DWIM is enabled (and a break is going to occur), faulteval also prints the offending form (in the case of a 
U.B.A., the parent form) and the name of the function which contains the form. For example, if FOO contains 
(CONS Х ЕТЕ) and ЕТЕ is unbound, faulteval prints: Џ.В.А. ЕТЕ [in FOO] in (CONS Х ЕТЕ). Note that if 
DWIM is not enabled, the user can obtain this information after he is inside the break via the IN? command. 


A similar procedure is followed whenever apply or apply* are called with an undefined function, i.e., one whose 
fntyp is NIL. In this case, faultapply is called giving it the function as its first argument and the list of arguments to 
the function as its second argument. The value returned by faultapply is used as the value of apply or apply*. 
faultapply is defined to print U.D.F. and then call Бгеак1 giving it (APPLY (QUOTE fn) QUOTE args)) as brkexp. 
Once inside the break, the user can define the function, return а specified value, etc. If the break is exited with a 
value, the computation will proceed exactly as though no error had occurred. faultapply is also called for undefined 
function calls from compiled code. 
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the section on breakcheck. Suffice it to say that the parameters affecting this decision have been 


ada empirically so that trivial type-in errors do not cause breaks, but deep errors do. 


16.2 TERMINAL INITIATED BREAKS 


CONTROL-H 


Section 15 on the break package described how the user could cause a break when a specified 
function was entered. The user can also indicate his desire to go into a break at any time while a 
program is running by typing control-H.? At the next point a function is about to be entered, (ће | 
function interrupt is called instead. interrupt types INTERRUPTED BEFORE followed by the 
function name, constructs an appropriate break expression, and then calls breakl. The user can _ 
then examine the state of the computation, and continue by typing OK, GO ог EVAL, and/or | 
гестот back to some previous point, exactly as with a user break. Control-H breaks are thus 
always "safe". Note that control-H breaks are not affected by the depth or time of the. 
computation. However, they only occur when a function is called, since it is only at this time that 
the system is in a "clean" enough state to allow the user to interact. Thus, if a compiled program 


_ is looping without calling any functions, or is in a I/O wait, control-H will not affect it. Control B, 


however, will. 


CONTROL-B 


Control-B is a stronger interruption than control-H. It effectively generates an immediate error. 
This error is treated like any other error except that it always causes a break, regardless of the | 
depth or time of the computation.’ Thus if the function FOO is looping internally, typing control-B _ 

will cause the computation to be stopped, the stack unwound to the point at which FOO was called, 


. and then cause a break. Note that the internal variables of FOO are not available in this break, and 


similarly, FOO may have already produced some changes in the environment before the control-B 
was typed. In other words, it may not be possible to simply continue the computation, depending 
оп the nature of the function interrupted and when it was interrupted. Therefore whenever | 
possible, it is better to use control-H instead of control-B. 


CONTROL-E 
If the user wishes to abort a computation, without causing a break, he should type control-E. | 


Control-E does not go through the normal error machinery of scanning the. stack, calling - 
breakcheck, printing a message, etc. as described below, but simply types a carriage- return and 


unwinds. 


_ As soon as control-H is typed, Interlisp clears and saves the input buffer, and then rings the bell, indicating that it is 
now safe to type ahead to the upcoming break. If the break returns a value, i.e., is not aborted via т or control-D, | 
the contents of the input buffer before the control-H was typed will be restored. 

. Control-H will not interrupt at linked function calls (see Section 18). 


However, sctting helpflag to NIL will suppress the break. See discussion of breakcheck below. 
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16.3 OTHER TYPES OF ERRORS 


. In addition to U.B.A. and U.D.F. errors, there are currently 28 other error types in Interlisp, 
e.g, P-STACK OVERFLOW, NON-NUMERIC. ARG, FILE NOT OPEN, etc. A complete list is 
given later in this section. When an error occurs, the decision about whether or not to break is 


handled by breakcheck and is the same as with U. B. A. and U.D.F. errors. If a break is to. 
occur, the exact action that follows depends on the type of error. For example, if a break is to- 


occur following evaluation oof | (RPLACA NIL (ADD1 5)) (which causes ап 
ATTEMPT TO RPLAC NIL error), the message printed will be (RPLACA BROKEN), brkexp will 
be (RPLACA U V W), U will be bound to NIL, V to 6, and W to NIL, and the stack. will look 
like the user had broken on rplaca himself. Following a NON -NUMERIC ARG error, the system will 
type IN followed by the name of the most recently entered function, and then (BROKEN). The 
system will then effectively be in a break inside of this function. brkexp will be a call to ERROR so 
that if the user types OK or EVAL or GO, а? will be printed and the break maintained. However, 
if the break is exited with a value via the RETURN command, 8 the computation will proceed exactly 
as though no error had occurred. | | 


16.4 ВВЕАКСНЕСК - МНЕМ ТО ВВЕАК. 


The decision as to whether or not to induce a break when an error occurs is handled by the 
function breakcheck.? The user can suppress all error breaks by setting the variable helpflag to NIL 
(initially set to T). If helpflag=T, the decision is affected by two factors: the length of time spent 
іп the computation, and the depth of the computation at the time of the error." If the time is 
greater than helptime or the depth is greater than helpdepth, breakcheck returns T, meaning a 
break will occur. Finally, if helpflag = BREAK 1, a ак will aways occur LOWE an error. 


Since a function is not actually entered пш its arguments are evaluated: п the depth of a 
computation is defined to be the sum of the number of function calls plus the number of internal 
calls to eval. Thus if the “| user types in the expression 
[MAPC FOO (FUNCTION (LAMBDA (X) (COND ((NOT (MEMB X FIE)) (PRINT X] for 
evaluation, and FIE is not bound, at the point of the U.B.A. FIE error, two functions, mapc and 
cond, have been entered, and there are three internal calls to eval corresponding to the evaluation 
of the forms (COND ( (NOT (MEMB X пеш (PRENI Х))), (МОТ (МЕМВ Х РТЕ)), апа 
(MEMB X ЕТЕ).!2 The depth is thus 5. _ 


breakcheck begins by searching back up the parameter stack looking for an errorset.? At the same 


8 Presumably the value will be a number, or the error will occur again. 

9 breakcheck is available to the user. for advising or redefining. It is a function of two arguments, е rrorpos, the stack 
position at which the error occurred, and erxn, the error number. | 

10 Except that control-B errors always break. 

ll — Unless of course the function does not have its arguments evaluated, i.e., is ап FEXPR, FEXPR*, CFEXPR, 
CFEXPR*, FSUBR ог FSUBR®, i 

12 For complete discussion of the stack and the interpreter, see Section 12. | А 

13 


errorsets are simply markers оп the stack indicating how far back unwinding is to take place when an error occurs, 
i.c., they segment the stack into sections such as that if an error occurs in any scction, control returns to the point at 
which the last errorset was entered, from which NIL is returned as the value of Ше errorset. See page 16.11. 
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time, it counts the number of internal calls to eval. As soon as (if) the number of calls to eval 
exceeds helpdepth, breakcheck can stop searching for errorset and return T, since the position of 
the errorset is only needed when a break Js not going to occur. Otherwise, breakcheck continues 
searching until ейһег an errorset is found!* or the top of the stack is reached. Breakcheck then 
completes the depth check by counting the number of function calls between the error and the last - 
errorset, or the (ор of the stack. If the number of function calls plus the number er of calls to eval | 
(already counted) is greater than or equal to helpdepth, initially set to 9, breakcheck returns Т. 
Otherwise, it records the position of the last errorset, and the value of errorset’s second argument, 
which is used in deciding whether to print the error message, and returns NIL. Note that if a — 
break is going to occur, the error message is printed regardless of the value of errorset’s second 

| argument. 


| breakcheck next measures the length of time spent in the computation by subtracting the value of 

the variable helpclock from the value of (CLOCK 2) 16 If the difference is greater than helptime 

milliseconds, initially set to 1000, then a break will occur, i.e, breakcheck returns T, otherwise | 

NIL. The variable helpclock is rebound to the current value of а 2) {ог еасһ oo 
typed in to lispx or to a break. 


The time criterion for breaking can be suppressed by setting helptime to NIL r a very big 
number), or by binding helpclock to NIL. Note that setting helpclock to NIL will not have any 
. effect because helpclock | is rebound by lispx and by break, 


If breakcheck is NIL, іс, а break is not going to occur, then if an errorset was s found, NIL is 
returned (via retfrom) as the value of the errorset, after first printing г the e error message if the 
 errorset'Ss second argument was non-NIL.! If there was no errorset, the message is рше and 
control returns to evalgt. This procedure is followed for all types of errors. 


Note that for all error breaks for which a break occurs, break] will еш апа $ауе Ше input buffer. 
ТЕ the break returns a value, 1.е., 15 not aborted via t or control-D, the input buffer will be restored 
as described in Section 15. 


16.5 ERROR TYPES - 


There are currently forty-plus error types in the Interlisp ѕуѕіет.18 They are listed below by error 
number. The error is set internally by the code that detects the error before it calls the error 
handling functions. It is also the value returned by errorn if called subsequent to that type of 
error, and is used bye errormess for ше; the error message. 


14 If the second алей {о the etrorset is INTE RNAL, the errorset is ignored and searching continues. See discussion 
of errorset, page 16.11. | 
15 Arrived at empirically, takes into account the overhead due to lispx or break. 
16 Whose value is number of milliseconds of compute time. See Section 21. 
Пп ү the value of nlsetqgag is NIL (initially T), the message will always be printed, regardless of the value of errorsets 
. second argument. 
18 


Some of бе errors are implementation dependent, 1.е., appear in Intetlisp-10 but may not appear in other Interlisp 
systems. 
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Error Types 


Most error types will print the offending expression following the message, е.р., NON-NUMERIC 
ARG NIL is very common. Error type 18 (control-B) always causes a break (unless helpflag is 
NIL).. АП other errors cause breaks if breakcheck returns Т. 


0 


19 


JSYS ERROR In Interlisp-10 occurs following a trap in a JSYS (see Section 21). 
no longer used. 


STACK OVERFLOW occurs when computation is too deep, either with respect to number 
of function calls, or number of variable bindings.” Usually because 
of a non-terminating recursive computation, ie. а bug. | | 


ILLEGAL RETURN call to return when not inside of an interpreted prog. 
ARG NOT LIST m e.g., rplaca called on a non-list. 


no longer used. 
ATTEMPT ТО SET NIL ма set ог setq 


ATTEMPT TO RPLAC NIL | | | | | 
attempt either to rplaca or to rplacd NIL with something other than 
NIL. 


UNDEFINED OR ILLEGAL GO 
£0 when not inside of a prog, or go to nonexistent label. 


As described in Section 21, TRAP AT LOCATION is printed, followed by the JSYS diagnostic, and control returns to 
the operating system executive, The user can then safely CONTINUE, and the Interlisp error, JSYS ERROR is then 
generated. A TRAP AT LOCATION can also occur if an illegal instruction is executed. In this case, the operating 
system also prints ILLEGAL INSTRUCTION. This can happen for example if the user is programming directly in 
ASSEMBLE code, or if his system somehow got smashed. In the latter case, it is quite possible that random 


programs or data structures might have already been smashed. Unless he is sure he knows what the problem is, the 


user is best advised to abandon this system as soon as possible. (If the user does elect to CONTINUE, Interlisp will 
(try to) generate а JSYS ERROR and unwind. In some cases, however, the system may be so badly smashed that the 
error message won't even print.) Note that in some cases, e.g. illegal instruction trap while in the garbage collector, 
Interlisp will print out CAN' T CONTINUE, because traps under those conditions are fatal. The user тау be able to 
reenter his sytem via the START command, and, if lucky, dump some data or functions before the system totally 
collapses. 


In Interlisp-10, the garbage collector uses the same stack as the rest of the system, so that if a garbage collection 
occurs when decp in a computation, the stack can overflow (particularly if there is a lot of list structure that is deep 
in the car direction). If this does happen, the garbage collector will flush the stack used by the computation in order 
that the garbage collection сап complete. Afterwards, the error message STACK OVERFLOW IN GC - 
COMPUTATION LOST is printed, followed by а reset[], i.e., return to top level. | 
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Section 16: Error Handling 


FILE WON' T OPEN From infile or outfile, Section 14. 


NON-NUMERIC ARG a numeric function e.g., iplus, itimes, igreaterp ; expected а number. 
ATOM TOO LONG In Interlisp-10, > 126 characters, 


ATON HASH TABLE FULL 
no room for any more (asan atoms. 


21 
FILE NOT OPEN | бош an I/O function, e.g., tee dob 7 


ARG NOT LITATOM e.g., setq, put, gettopval, etc., given a non-atomic arg. 


TOO MANY FILES OPEN | | 
> 30 оша terminal. 


END OF FILE from an input function, e. 8- read, reads, ratom. Note: the file will 
then be closed. - | 

ERROR — — call to error. 

BREAK control-B was typed. 


ILLEGAL STACK ARG a stack function expected a stack position and was given something 
| else. This might occur if the arguments to а stack function are 
reversed. Also occurs if user specified a stack position with a 
function name, and that function was not found on the stack. See 
Section 12. 


FAULT IN EVAL artifact of bootstrap. Never occurs after faulteval has been defined 
as described earlier. | 


Іп Interlisp-10, the atom hash table will automatically expand by а specified number of pages each time it fills ро. 
until an upper limit of 32K atoms is reached. | | | 


The entries on errortypelst (described below) аге processed before the Ме is closed, so that the user can intercept 
and process this error via an entry on errortypelst, thereby preventing the file from being closed. It is also possible 
to use an errortypelst entry to return a character as the value of the call to errorx, and the program will continue, 


. eg. returning "|. may be used to complete a read operation. 
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.. Error Types 


ARRAYS FULL system will first initiate a garbage collection of array space, and if 
no array space is reclaimed, will then generate this error. 
FILE SYSTEM RESOURCES EXCEEDED | B 
(Interlisp-10) includes no more disk space, disk quota exceeded, 
. directory full, too many ms We full. 
FILE NOT FOUND Не name does not correspond to a file in the corresponding | 
| | · directory.2? Can also occur if Ме name is ambiguous. 
BAD SYSOUT FILE date does not agree with date of makesys, ‹ or file is not a а sysout file 
~ at all (see section 14). 
UNUSUAL CDR ARG LIST 
a form ends in a non-list other than NIL, е. (CONS T. 3). 
HASH TABLE FULL see hash link functions, Section 7. 
ILLEGAL ARG . Catch-all error. Currently used dd putd, evala, a arg, funarg, allocate, 
| rplstring, etc. 
ARG МОТ ARRAY elt or seta given an ОНЕ {һа{ 15 поѓ а pointer to the beginning 
of an аггау. 
ILLEGAL OR IMPOSSIBLE BLOCK 
(Interlisp-10) from getblk or relblk. See Section 21. 
STACK PTR HAS BEEN RELEASED | 
a released stack pointer was applied: as a stack с бон бог а 
purpose other than as a stack pointer to be re-used (see Section 12). 
STORAGE FULL following a garbage collection, if a sufficient amount of words has 
not been collected, and there is no un-allocated space left in the 
system, this error is generated. | 


Interlisp is initialized with an entry on errortypelst (described below) to call spellfile (Section 17) for error 23. 
spellfile will search alternate directories or perform spelling correction on the connected directory. If spellfile fails, 
then the user will see this error. 
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Section 16: Error Handling 


ATTEMPT TO USE ITEM OF INCORRECT TYPE _ 
Before a field of a user-data type 15 changed, the type of the item 15 
first checked to be sure that it is of the oe type. If not, this 
error is generated. See Section 23. 


ILLEGAL DATA TYPE NUMBER ә 
The argument is not a valid user-data type number. See Section 
„23. 


DATA TYPES FULL All available user-data types have been allocated. See Section 23. 


ATTEMPT TO BIND NIL OR T 
in a prog or lambda expression. 


тоо MANY USER ‘INTERRUPT CHARACTERS 


Attempt to enable a user interrupt character when all 9 user 
channels are currently enabled. See page 16.12. | 


READ- MACRO CONTEXT ERROR 


Occurs when a read is saa from within a read-macro function 
and the next token is a ) ога]. See Section 14. сы - 


1 LLEGA L READTABLE The argument was expected to be a valid readtable. „бес Section 


ом. 


ILLEGAL TERMINAL TABLE | | 
The argument was expected to be a valid terminal table. See 
Section 14. 


 SWAPBLOCK TOO BIG FOR BUFFER 
(Interlisp- 10) An attempt. was made to swap in a functions 
which is too large for the swapping buffer. See setsbsize, Section 3. 


PROTECTION VIOLATION 
 (Interlisp- 10) attempt to open a file that user does not have access 
to. Also reference to unassigned device. 


BAD FILE NAME illegal character in file specification, illegal syntax, e.g. in Interlisp- 
10, two ;'s etc. | 


USER BREAK | Error corresponding to "hard" uscr-interrupt character. See page 
16.12. | | 
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Error Types 


In addition, many system functions, e.g., define, arglist, advise, log, exp t, etc, also generate errors 
with appropriate messages by calling error (see page 16.10) which causes an error of type 17. 


ERROR HANDLING BY ERROR TYPE 


Occasionally the user may want to treat certain error types differently from others, e.g., always 
break, never break, or perhaps take some corrective action. This can be accomplished via 
errortypelst. errortypelst is a list of elements of the form (n expression), where n is one of the 28 
error numbers. After breakcheck has been completed, but before any other action is taken, 
errortypelst is searched for an element with the same error number as that causing the error. If 


one is found, and the evaluation of the corresponding expression produces a non-NIL value, the | 


value is substituted for the offender, and the function causing the error is reentered. 


For this application, the following three variables may be useful: 


errormess | car is the error number, cadr the "offender" | eg, (10 NIL) 
| corresponds to NON-NUMERIC ARG NIL error. 


errorpos | J position of the function in which the error occurred, eg. 
| | . stknameferrorpos] might be ш RPLACA, Я etc. 


breakchk value of breakcheck, ie, Т means a break will оссиг, N IL means 
one will not. 


For example, putting 


[10 (AND (NULL (CADR ERRORMESS) ) 
(SELECTQ (STKNAME ERRORPOS) 
((IPLUS ADD1 SUB1) 0) 
(ITIMES 1) 
(PROGN (SETQ BREAKCHK T) NIL] 


оп е errortypelst would specify that whenever a NON-NUMERIC ARG - NIL error occurred, and the 
function in question was IPLUS, ADD1, or SUB1, 0 should be used for the NIL. If the function 


was ITIMES, 1 should be used. Otherwise, always break. Note that the latter case is achieved 
not by the value returned, but by the effect of the evaluation, i.e., setting BREAKCHK to T. 


Similarly, (16 (SETQ BREAKCHK NIL)) would prevent END OF FILE errors from ever 
breaking. 


printmsg if T, means print error message, if NIL, don't print error message, 


i.e., corresponds to second argument to errorsct. The user can force | 


or suppress the printing of error message for various errortypes by 


including оп crrortypelst an expression which explicitly sets | 


printmsg. 


Note: If the error is going (0 Бе handled by а retfrom, retto, or а reteval іп the errortypelst entry, 
it probably is a good idca to first release the stack pointer сггогроѕ, e.g. by performing 
(RELSTK ERRORPOS). 
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The initial value of errortypelst is ((23 (SPELLFILE (CADR ERRORMESS)))), which causes 
зре е (Section 17) to be called in case of a FILE NOT FOUND error. If spellfile is successful, 
the operaion will be recxecuted with the new (corrected) file name. | 


16.6 ERROR FUNCTIONS 


errorx[erxm] 


 error[messl;mess2;nobreak] 


help[mess1;mess2] 


shouldnt[] 


error![] 


24 


25 Pronounced "error-bang". 


is the entry to the error routines. If erxm=NIL, errorn[] is used 
to determine the | error-message. Otherwise, | 
seterrorn[car[erxm];cadr[erxm]] is performed, "setting" the error 
type and argument. Thus following either еггогх[ (10 T)] or 
(PLUS T), егог | is (10 Т). errorx calls breakcheck, and either 


induces a break or prints the message and unwinds to the last — 


errorset. Note that errorx сап be called by any program to 7 


intentionally induce an error of any type. However, for most — 
applications, the function error will be more useful. 


The message that is (will be) printed is messl (using prin inl), 
с followed by a space if messl is an atom, otherwise a carriage return. 


Then mess2 is printed, using prinl if mess2 is a string, otherwise 
print, с.р, e.g., error[ "МОМ- NUMERIC ARG"; Т] will print "E 


. NON- NUMERIC ARG | 


- | | | 
апд error[ Ё00; "NOT А FUNCTION" ] . . will print | 
FOO NOT A FUNCTION. (If both mess] and mess2 are NIL, the Е 
message is Suny. ERROR.) — | са 


If nobreak=T, error ЕТТЕ its message and then calls егтог!. 2А 


Otherwise it calls 115 errorx[(17 (messl. mess2))], ie, generates ап 


error of type 17, in which case the decision as to whether or not to 
break, and whether or not to print a message, is handled as per any 
other error. "M 


prints messl and mess2 a la error, and then calls breakl. If both 
messl and mess2 are NIL, HELP! is used for the message. help is _ 
a convenient way to program a default condition, or to terminate 
some portion of a program which the computation is шешу | 


never supposed to reach. 


for those situations when a program detects a condition that should 
never occur. Calls help with the message "Shouldn't ћаррвп!". 


programmable control-E, ie., immediately returns from last errorset 


or resets. 


unless the value of helpflag is BREAK!, in which case a break will always occur, as described earlier, 
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Error Functions 


гезе programmable control-D, 1.е., immediately returns to the top level. 


errorn[] returns information about the last error in the form (n x) where n 
is the error type number and x is the expression which was (would 
have been) printed out after the error message. Thus following 
(PLUS T), errorn[] is dia. P. 


seterrorn[num;mess] . gets errorn: after setterrorn[num; mex has been енемін errorn{] 
will return (num mess). | 


errormess[u] | | prints message corresponding to ап errorn that yielded u. For | 
example, errormess[(10 Т)] would print 
NON-NUMERIC ARG 
T 


errorstring[n] : = returns as a new string the message corresponding to an error of 
type n, e.g. errorstring[10] "НОН- NUMERIC ARG". 


errorset(form; По:-|26 performs eval[form]. Note that errorset is a lambda-type of 
function, and that its arguments are evaluated before it is entered, 
ie. errorset[x] means eval is called with the value of х. In most 
cases, ersetq and преѓа q (described below) are more useful. If no 
error occurs in the evaluation of form, the value of errorset is a list 
containing one element, the value of eval[form]. If an error did 
occur, the value of errorset is NIL. | 


The argument flg controls the printing of error messages if an error 
occurs. If flg- T, the error message is printed; if flg —NIL it is 
not, unless the value of nlsetqgag is NIL, (initially Т).““ Note that if 
a break occurs due to an error below an errorset, the message is 
printed regardless of the value of flg. | 


If flg=INTERNAL, the errorset is ignored Юг the purpose of 
deciding whether or not to break or print a message. However, the 
errorset is in effect for the purpose of flow of control, i.e., и ап 
error occurs, this errorset returns NIL. ии 


If Пр = NOBREAK, no break will occur, even if the time criterion for 
breaking is met. Note that Пр-- МОВВЕАК will not prevent a break 
from occurring if the error occurs more than helpdepth function 
calls below the errorset, since breakcheck will stop searching before 


26 errorset is a subr, so the names "form" and "flg" don't actually appear on the stack nor will they affect the 


evaluation. * 


27 


In other words, nlsctqgag provides а global override оп errorsets, effectively changing all nlsetqs to ersetgs. 
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. it reaches the errorset, as. explained on page 16.3. To guarantee 
that no break occurs, the user would also either have to reset 


helpdepth « Or helpflag. 


| ersetqfersetx] | ~ nlambda, performs errorset[ersetx; T] ie, (ERSETQ (Е 00)) is 


equivalent to ( ERRORSET O ( FOO) ) T). 
nlsetq[nisetx] | | (0 . nlambda, енші кн, NIL]. 


16.7 INTERRUPT CHARACTERS 


This section describes how the user can disable and/or redefine Interlisp interrupt characters, as | 
well as defining his own interrupt characters. Interlisp is initialized with 8 interrupt channels which | 
we shall call: HELP, PRINTLEVEL, STORAGE, RUBOUT, ERROR, RESET, 
OUTPUTBUFFER, and BREAK. To these are assigned respectively, control-H, control-P, control- 
S, delete/rubout, control-E, control-D, control-O, and сопио-В. Each of these channels 
independently can be disabled, or have a new interrupt? character assigned to it via the function 
interruptchar described below. In addition, the user can enable up to 9 new interrupt channels, | 
and associate with each channel an interrupt character and an expression to be evaluated when that 
character is typed. User interrupts can be either "hard" or "soft". A "hard" interrupt is like 
control-E or control-D: it takes place as soon as it is (уред. А soft interrupt is like control-H; it 
does not occur until the next function call39 Soft interrupts can always be safely continued from. 
Hard interrupts rip the system out of the function currently being executed and unwind back to 
the last function call, ie. part of the computation that was interrupted is lost and cannot be 
continued. 


арена На (ур/ form; 'hardflg] 
char is either a character or a terminal interrupt code?! 


If typ/form=NIL, char is disabled. If typ/form— T, the current 
state of char is returned without changing it. 


28 TENEX requires that interrupt сипеи бе one of control-A, B,...,Z, space, Sd шшс ог мА 
29 Hard interrupts аге kübiemented by generating an error of type 43, and retrieving the RE form from the | 
^ list userinterrupts once inside of errorx. Soft interrupts are implemented by calling i interrupt with an appropriate third 
argument, and then obtaining the corresponding form from userinterrupts. In either case, if a character is enabled as 
a user interrupt, but for some reason it is not found on userinterrupts, an UNDEFINED USER INTERRUPT error _ 
will be generated. 
30 As soon as a soft interrupt character is typed, Interlisp clears and saves the input buffers, and then rings the bell. 
After the interrupt form is evaluated, the input buffers are restored. | 
3l The terminal interrupt code for break is 0, for esc is 27, for rubout/delete is 28, and for space is 29. The terminal 
interrupt codes for the control characters can be obtained with chconl. 
32 


The current state is an expression which can be given back to intcruptchar to restore that : State. This option is used 
in connection with undoing and resctform. | | | 
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Interrupt characters 


If typ/form is a literal atom and the name of one of the 8 Interlisp 
interrupt channels given above: HELP, PRINTLEVEL.,....,BREAK. 
interruptchar assigns char to that channel, (reenabling the channel if 
previously disabled). Otherwise, char is enabled as an interrupt 
character that when typed causes typ/form to be immediately set to 
T. If char was previously defined as an interrupt character, that 
interpretation is disabled. | 


If typ/form is а list, char is enabled as a user interrupt character, 
and typ/form is the form that is evaluated when char is typed. The 
interrupt will be hard if hardflg =T, otherwise soft. Any previous 
interpretations of char are disabled. | X 


All calls to interruptchar are undoable. In addition, the value of 


interruptchar is an expression which when given back to 
interruptchar will restore things as they were before the call to 
interruptchar. Thus, interruptchar can be used in conjunction with 
resetform or resetlst (see Section 5). | 


Note: interruptchar[T] will restore all Interlisp channels to their original state, and disable all user 
interrupts. | | ми 


interruptable[flg] if flg - NIL, turns interrupt off. If flg=T, turns interrupt on. 
Value is previous setting. interruptable compiles open. | | 


Note: Any interrupt character typed while interrupts are off is treated the same as any other 
character, i.e. placed in the input buffer, and will not cause an interrupt when interrupts are turned 
back on. 


interruptablepl[] value is T, if interrupts are enabled, NIL if disabled. 


я 
| 
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SECTION 17 a 
AUTOMATIC ERROR CORRECTION - THE DWIM FACILITY! — 


17.1 INTRODUCTION 


A surprisingly large percentage of the errors made by Interlisp users are of the type that could be 
corrected by another LISP programmer without any information about the purpose of the program 
or expression in question, e.g., misspellings, certain kinds of parentheses errors, etc. To correct 
these types of errors we have implemented in Interlisp a DWIM facility, short for Do-What-I- 
Mean. DWIM is called automatically whenever an error? occurs in the evaluation of an Interlisp 
expression. DWIM then proceeds to try to correct the mistake using the current context of 
computation plus information about what the user had previously been doing, (and what mistakes 
he had been making) as guides to the remedy of the error. If DWIM is able to make the 
correction, the computation continues as though no error had occurred. Otherwise, the procedure 
is the same as though DWIM had not intervened: a break occurs, or an unwind to the last errorset, 
as described in Section 16. The following protocol illustrates the operation of DWIM. 


EXAMPLE 
The user defines a function fact of one argument, n. The value of fact[n] is to be n factorial. 


-DEFINEQ((FACT (LAMBDA (М) (COND | 
((ZEROP N9 1) ((T (ITIMS N (FACCT 8SUB1 N] 
(FACT) | 


+ 


Note that the definition of fact contains several mistakes: itimes and fact have been misspelled; the 
9 in М9 was intended to be a right parenthesis, but the shift key was not depressed; similarly, the 
8 in 8SUB1 was intended to be a left parenthesis; and finally, there is an extra left parenthesis in 
front of the T that begins the final clause in the conditional. 


1 


DWIM was designed and implemented by W. Teitelman. It is discussed іп [Tei2]. 


Currently, DWIM only operates on unbound atoms and undefined function errors. 
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-PRETTYPRNT( ( FACCT] [1] 
-PRETTYPRINT |. [2] 
-FACT | | [3] 
(FACT 

[LAMBDA (N) 

|. (COND 


((ZEROP М9 1) 
(СТ (ІТІМЅ N (FACCT 8SUB1 М1) 
(FACT) | 


After defining fact, the user wishes to look at its definition using PRETTYPRINT, which he . 
unfortunately misspells. [1] Since there is no function PRETTYPRINT in the system, a U.D.F. error 
occurs, and DWIM is called. DWIM invokes its spelling corrector, which searches а list of 
functions frequently used (by this user) for the best possible match. Finding one that is extremely 
close, DWIM proceeds on the assumption that PRETTYPRNT meant PRETTYPRINT, notifies the 
user of this, Dl and calls prettyprint. 


At this point, PRETTYPRINT would normally print (FACCT NOT — and exit, since 
facct has no definition. Note that this is по/ an Interlisp error condition, so that DWIM. NOU not _ 
be called as described above. However, it is obviously not what the user meant, | | 


This sort of mistake is corrected by having prettyprint itself explicitly invoke the spelling corrector 

portion of DWIM whenever given a function with no expr definition. Thus with the aid of 
DWIM, prettyprint is able to determine that the user wants to see the definition DE the function | 
fact [3] and proceeds accordingly. 


«ҒАСТ(31 | . [4] 
М9 [IN FACT] -> М) ? YES | . 
[IN FACT] (COND -- ((T --))) - 

(COND -- (T --)) | 
ІТІМ5 [IN FACT] -> ITIMES [5] 
FACCT [IN FACT] -> FACT | 
85081 [IN FACT] -> ( 5981? YES 
6 | | 
PP FACT _ | [6] 


(FACT 
[LAMBDA (N) 
(COND | 
((ZEROP М) 
1 


| . (T (ITIMES М (FACT (5081 М1) 
FACT 


€ 


The user now calls his function fact.[4] During its execution, five errors occur, and DWIM is called 
five times[5] At each point, the error is corrected, a message printed describing the action taken, 
and the computation. allowed to continue as if no error had occurred. Following the last 
correction, 6 is printed, the value of Шы; Finally, the user prettyprints the new, now correct, 
definition of fact.[6] | 


In this particular example, the user was shown operating in TRUSTING mode, which gives DWIM | 
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carte blanche for most corrections. The user can also operate in CAUTIOUS mode, in which case 
_ DWIM will inform him of intended corrections before they are made, and allow the user to 
approve or disapprove of them. For most corrections, if the user does not respond іп a specified | 
interval of time, DWIM automatically proceeds with the correction, so that the user need intervene 
only when he docs not approve. Sample output is given below. Note that the user responded to 
the first, second, and fifth questions; DWIM responded for him on the third and fourth. 


«ҒАСТ(3) | | 
МО [IN FACT] -> М)? YES | [1] 
U.D.F. T [IN FACT] FIX? YES 00 [2] 


ГІН FACT] (COND -- ((T --))) -> 
(COND -- (T --)) 


ITIMS [IN FACT] -> ITIMES ? ...YES [3] 
FACCT [IN FACT] ->-FACT ?  ...YES  ——— [4] 
8SUB1 [IN FACT] -> ( SUB1 ? NO —— — [5] 
U.B.A. | | 


(8SUB1 BROKEN) 


. We have put a great deal of effort into making DWIM "smart", and experience with perhaps fifty 

different users indicates we have been very successful; DWIM seldom fails to correct an error the 
user feels it should have, and almost never mistakenly corrects an error. However, it is important 
to note that even when DWIM is wrong, no harm is done:? since an error had occurred, the user 
would have had to intervene anyway if DWIM took no action. Thus, if DWIM mistakenly corrects 
an error, the user simply interrupts or aborts the computation, UNDOes the DWIM change using 
UNDO described in Section 22, and makes the correction he would have had to make without 
DWIM. It is this benign quality of DWIM that makes it a valuable part of Interlisp. 


17.2 INTERACTION WITH DWIM 


DWIM is enabled by performing either DWIM[C], for CAUTIOUS mode, or DWIM[T] for 
TRUSTING тойс.“ In addition to setting dwimflg to T and redefining faulteval and faultapply as 
described on page 17.10, DWIM[C] sets approveflg to T, while DWIM[T] sets approveflg to NIL. 
The sctting of approveflg determines whether or not the user wishes to be asked for approval 
и а correction that will modify the definition of one of his functions. In CAUTIOUS mode, 

approveflg=T, DWIM will ask for approval; in TRUSTING mode, DWIM will not. For 
COCOS to expressions typed in by the user for immediate execution? DWIM always acts as 


3 Except perhaps if DWIM's correction mistakenly caused a destructive computation to be initiated, and information 
was lost before the user could interrupt. We have not yet had such an incident occur. 


3 Interlisp arrives with DWIM enabled in CAUTIOUS mode. DWIM сап be disabled by executing DWIM[] or by 
setting dwimflg to NIL. See page 17.20. 


Турса into lispx. lispx is used by evalqt and break, as well as 5 for processing the editor's E command. Functions that 


type-in, so that corrections to Бей will never require d Commands given as an argument to the editor, or 
resulting from macro expansions, or from IF, LP, ORR commands ctc. are not treated as type-in, and thus 
approval will be requested if approveflg = T 
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though approveflg were NIL, 1.е., no approval necessary. 6 In either case, DWIM always informs the 
user of its action as described below. 


SPELLING CORRECTION PROTOCOL 


The protocol used Бу DWIM for spelling corrections is as follows: If the correction occurs in type- 
in, print = followed by the correct spelling, followed by a carriage-return, and then continue, e.g., 


user types: “(SETQ FOO (NCOCN FIE FUM)) 
DWIM types: -NCONC 


the correction does not occur in type-in, print the incorrect spelling, followed by [IN function- 
ame], - - >, and then the correct spelling, e.g; ITIMS [IN FACT] -> ITIMES as shown on page 
17. 2. Then, if approveflg=NIL, print a carriage return, make the correction and continue. 


Otherwise, print a few spaces and a ? and then wait for approval: 8 The user then has six options. | 


He can: 
1. Туре Ү; DWIM types es, and proceeds with the correction. 
2. Type М; DWIM types o, and does not make the correction. 


3. Туре т; DWIM does not make the correction, and furthermore guarantees that the 
error will not cause a break. See footnote on page 17.10. 


4. Туре control- E: for error correction, this has the same effect as typing N. 


5. Ро nothing; in which сазе DWIM will wait a specified interval, 10 and if the user has 
not responded, DWIM will type ... followed by the default answer.!! 


6. Type space or carriage-return; in which case DWIM will wait шай: This option 
is intended for those cases where the user wants to think about his answer, and wants. 
to insure that DWIM does not get "impatient" and answer for him. 


о. For certain types of corrections, e. g., run-on spelling corrections, 8- 9 errors, etc, ПАЛМ алау asks for approval, _ 
. regardless of the setting of approveflg. | 

1 The appearance of - > is to call attention to Ше fact that the user's function will be or has been changed. 

8 DWIM uses askuser for its interactions with the user (page 17.22). Whenever an interaction is about to take place 
and the user has typed ahead, askuser types several bells” to warn the user to stop typing, then clears and saves the 
input buffers, restoring them after the interaction is complete. Thus if the user has typed ahead before a DWIM 
interaction, DWIM will not confuse his type ahead with the answer to its question, nor will his typeahead be lost. 

9 The bells are printed by the function printbells, which can be advised or redefined for specialized applications, e.g. to 
flash the screen for a display terminal. 

10 Equal to dwimwait seconds. DWIM operates by dismissing for 250 milliseconds, then checking to see if anything has 
been typed. If not, it dismisses again, etc. until dwimwait seconds have elapsed. Thus, there will be a delay of at 
most 1/4 second before DWIM responds to the user's answer. 

11. 


The default оп spelling corrections is determined by the value of the variable fixspelldefault, whose top level value is 
initially Ү. 


т 


Interaction with Dwim 


The procedure for spelling correction on other than Interlisp errors is analogous. If the correction 
is being handled as type-in, DWIM prints = followed by the correct spclling, and returns it to the 
. function that called DWIM, e.g., =FACT as shown on page 17.2. Otherwise, DWIM prints the 
incorrect spelling, followed by the correct spelling. Then if approveflg = NIL, DWIM prints a 
carriage-return and returns the correct spelling. Otherwise, DWIM prints a few spaces and a ? and 
then waits for approval. The user can then respond with Y, N, control-E, space, carriage return, 
or do nothing as described. | 


Note that since the spelling corrector itself is not errorset protected, typing N and typing control-E 
may have different effects when the spelling corrector is called directly.% The former simply 
instructs the spelling corrector to return NIL, and lets the calling function decide what to do next; 
the latter causes an error which unwinds to the last errorset, however far back that may be. 


PA RENTHESES ERRO RS PROTOCOL 


As illustrated earlier оп. page 17.2, DWIM will correct errors consisting of typing 8 for left 
parenthesis and 9 for right parenthesis. In these cases, the interaction with the user is similar to 
that for spelling correction. If the error occurs in type-in, DWIM types = followed by the 
correction, e.g., | 


user types: «(SETQ FOO 8СОМ5 ЕТЕ ЕОМ] 
DWIM types: = ( CONS 
lispx types: (A B C D) 


Otherwise, DWIM prints the offending atom, [IN function-name], - >, the Рторозее correction, а 

few spaces and а ?, апа then waits for approval, е.р., М9 [IN FACT] -> М ) ? as shown оп 

page 17.2. The user then has the same six options as for spelling correction. 14 If the user types Ү, 

<- DWIM then operates exactly the same as when approveflg=NIL, i.e., makes the correction and 
prints its message. | 


U.D.F. Т ERRORS PROTOCOL 
DWIM corrects certain types of parentheses errors involving a T clause in a conditional, nama 


errors of the form: 


l. (COND --) (T --), i.e., the T clause appears outside and immediately following the 
COND; | | | 


2. (COND -- (-- & (T --))), i.e., the T clause appears inside a previous clause; and 


12 The DWIM error correction routines are errorset protection. 

13 Actually, DWIM uses the value of the variables Iparkey and rparkey to determine the corresponding lower case 
character for left and right parentheses. Ірагкеу and rparkey are initially 8 and 9 respectively, but they can be reset 
for other keyboard layouts, e.g., on some terminals left parenthesis is over 9, and right parenthesis is over 0. 

14 


except the waiting time is 3*dwimwait seconds. 
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3. (COND -- ((T --))), ie, the T clause has an extra pair of аа around 
it.) 


If the error occurs in Гая DWIM simply types Т FIXED and makes the correction. Otherwise 
if approveflg - NIL, DWIM makes the correction, and prints a message consisting of [IN function- 
name], followed by one of the above incorrect forms of COND, followed by ->, then on the next 
line the corresponding correct form of the COND, e.g., : 


[IN FACT] (COND -- ((Т --))) -> 
(COND -- (T --)) | 


as shown on page 17.2. | 
If арргоуейр-Т, DWIM prints U.D.F. T, followed by [IN function-name], several spaces, and. 
then FIX? and waits for approval. The user then has the same options as for spelling corrections 
and parenthesis errors. If the user types Y or defaults, DWIM then proceeds exactly the same as 
when approveflg = NIL, i.e., makes the correction and prints its message, as shown on page 17.3. 


Having made the correction, DWIM must then decide how to proceed with the computation. In 


case 1, (COND --) (T --), DWIM cannot know whether the last clause of the COND before the __ 
T clause succeeded or not, i.e., if the T clause had been inside of the COND, would it have been _ 


entered? Therefore DWIM asks the user ' CONTINUE WITH T CLAUSE' (with a default of YES). | 
If the user types М, DWIM continues with the form after the COND, i.e., the form that ы 
followed the Т clause. 


In case 2, (COND -- (-- & (T --))), DWIM has a different problem. After moving the Т 
clause to its proper place, DWIM must return as the value of the COND, the value of the | 
expression corresponding to &. Since this value is no longer around, DWIM asks the user, 
"ОК ТО REEVALUATE' and then prints the expression corresponding to &. If the user types Y, 
or defaults, DWIM continues by reevaluating &, otherwise ПМ aborts, and а U.D.F. T error 
will then occur (even though the COND has in fact been бхед).15 


In case 3, (COND -- ((T --))), there is no problem with continuation, so no further 
interaction is necessary. | 


5 For U.D.F. T errors that are not one of these three types, DWIM takes no corrective action at all, 1.е., the error 


will occur. 


If DWIM can determine for itself that the form can safely be reevaluated, it does not consult the user before | 
recvaluating. DWIM can do this if the form is atomic, or car of the form is a member of the list okreevalst, and 
cach of the arguments can safely be reevaluated, e.g.. (ФЕТО X (CONS (IPLUS Y 2) w)) is safe to reevaluate 
because SETQ, CONS, and IPLUS are all on okrcevalst. | | 
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Spelling Correction 


17.3 SPELLING CORRECTION 


The spelling corrector is given as arguments a misspelled word (word means literal atom), a 
spelling list (a list of words), and a number: xword, splst, and rel respectively. Its task is to find 
that word on splst which is closest to xword, in the sense described below. This word is called a 
respelling of xword. rel specifies the minimum "closeness" between xword and a respelling. If the 
spelling corrector cannot find a word on splst closer to xword than rel, or if it finds two or more 
words equally close, its value is NIL, otherwise its value is the respelling.! 


The exact algorithm for computing the spelling metric is described later on page 17.16, but briefly - 


"closeness" is inversely proportional to the number of disagreements between the two words, and 
directly proportional to the length of the longer word, e.g, PRTTYPRNT is "closer" to 
PRETTYPRINT than CS is to CONS even though both pairs of words have the same number of 
disagreements. The spelling corrector operates by proceeding down splst, and computing the 
closeness between each word and xword, and keeping a list of those that are closest. Certain 
differences between words are not counted as disagreements, for example a single transposition, 
e.g., CONS to CNOS, or a doubled letter, e.g., CONS to CONSS, etc. In the event that the spelling 
corrector finds a word on splst with no disagreements, it will stop searching and return this word as 
the respelling. Otherwise, the spelling corrector continues through the entire spelling list. Then if 
it has found one and only one "closest" word, it returns this word as the respelling. For example, 
if xword is VONS, the spelling corrector will probably return CONS as the respelling. However, if 
xword is CONZ, the spelling corrector will not be able to return a respelling, since CONZ is equally 
close to both CONS and COND. If the spelling corrector finds an acceptable respelling, it interacts 
with the user as described earlier. 


In the special case that the misspelled word contains one or more «esc? s, the spelling corrector 
searches for those words оп splst that match xword, where an «esc? (alt-mode on some terminals) 
can match any number of characters (including 0), е.р., FOO$ matches Ғ001 and FOO, but not 
NEWFOO. $FOO$ matches all three. Both completion and correction may be involved, e.g. 
RPETTYS$ will match PRETTYPRINT, with one mistake. The entire spelling list is always searched, 
and if more than one respelling is found, the spelling corrector prints AMBIGUOUS, and returns 
NIL. For example, СОМФ would be ambiguous if both CONS and COND were on the spelling list. 
If the spelling corrector finds one and only one respelling, it interacts with the user as described 
earlier. 


For both spelling correction and spelling completion, regardless of whether or not the user 
approves of the spelling corrector's choice, the respelling is moved to the front of splst.! Since 
many respellings are of the type with no disagreements, this procedure has the effect of 
considerably reducing the time required to correct the spelling of frequently misspelled words. 


SYNONYMS 


Spelling lists also provide a way of defining synonyms for a particular context. ТЕ a dotted pair 
appears on a spclling list (instead of just an atom), car is interpreted as the correct spelling of the 
misspelled word, and cdr as the antecedent for that word. If car is identical with the misspelled 


П те spelling corrector can also be given an optional functional argument, fn, to be used for selecting out a subset of 
splst, i.e., only those members of splst that satisfy fn will be considered as possible respellings. 
18 


fixspcll has an optional argument, dontmovctopflg. which can be used to suppress moving the respelling. 
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word, the antecedent is returned without any interaction or approval being necessary. If the 
misspelled word corrects to car of the dotted pair, the usual interaction and approval will take 
place, and then the antecedent, i.e., cdr of the dotted pair, is returned. For example, the user could 
make IFLG synonymous with CLISPIFTRANFLG by adding (IFLG . CLISPIFTRANFLG) to 
spellings3, the spelling list for unbound atoms. Similarly, the user could make OTHERWISE mean 
the same as ELSEIF by adding (OTHERWISE . ELSEIF) to clispifwordsplst, or make | be 
synonymous with LAMBDA by adding (L . LAMBDA) to lambdasplst. Note that | could also be 
used as a variable without confusion, since the association of L with LAMBDA occurs ову іп Ше 
appropriate context. 


‘SPELLING LISTS 


Any list of atoms can be used as a spelling list, e.g., ES S filelst, etc. Various еш 
packages have their own spellings lists, e.g., lispxcoms, prettycomsplst, clispforwordsplst, editcomsa, 
etc. These are documented under their corresponding sections, and are also indexed under "spelling 
lists." In addition to these spelling lists, the system maintains, i.e. automatically adds to, and 
occasionally prunes, four lists used solely for spelling correction: spellings], spellings2, 5 spellings3, | 
and userwords.! 


Spellingsl is a list of functions used for spelling correction when an input is typed in apply format, 


and the function is undefined, e.g., EDTIF(FOO). Spellingsl is initialized to contain defineg, E 


break, makefile, editf, tcompl, load, etc. Whenever lispx is given an input in apply format, ie, a | 
function and arguments, the name of the function is added to spellings]. For example, typing E 
CALLS(EDITF) will cause CALLS to be added to spellingsl. Thus if the user typed 
CALLS(EDITF) and later typed CALLLS(EDITV), since Ж would then contain CALLS, | 
DWIM would be successful in correcting CALLLS to CALLS. 


Spellings2 is a list of functions used for spelling correction for all other undefined functions. It is 
-initialized to contain functions such as addl, append, cond, cons, ро, list, nconc, print, prog, return, 
setq, etc. Whenever lispx is given a non-atomic form, the name of the function is added to 
spellings2. For example, typing (RETFROM (STKPOS (QUOTE FOO) 2)) to a break would add 
retfrom to spellings2. Function names are also added to spellings2 by define, defineq, load (when 
loading compiled code), unsavedef, editf, and prettyprint. 


Spellings3 is a list of words used for spelling correction on all unbound atoms. Spellings3 is 
initialized to editmacros, breakmacros, brokenfns, and advisedfns. Whenever lispx is given an atom 
to evaluate, the name of the atom is added to spellings3. 22 Atoms are also added to spellings3 
whenever they are edited by editv, and whenever they are set via rpaq or rpaqq. For example, 
when а file is loaded, all of the variables set in Ше file are added to spellings3. Atoms аге also | 
added to  spellings3 when they ае set by а  lispx Шри, ер, typing 

(ФЕТО FOO (REVERSE (SETQ ЕТЕ --))) will add both FOO and ЕТЕ tospellingsà3. 


19 АП of the remarks on maintaining spelling lists apply only when addspellflg — T, its initial value. 
20 Only if the function has a definition. 
21 


И CALLLS(EDITV) were typed before CALLS had been "seen" and added to spellings], the correction would not 
succeed. However, the alternative to using spelling lists is to look at all the atoms in the system, a procedure that 
would make spelling correction intolerably slow, 


22 Only if the atom has a value other than NOBIND. 
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Userwords is а list containing both functions and variables that the user has referred to, e.g., by 
breaking or editing. Userwords is used for spelling correction by arglist, unsavedef, prettyprint, 
break, editf, advise, etc. Userwords is initially NIL. Function names are added to it by define, 


дећпеа, 10: load, (when loading compiled code, or loading exprs to property lists) unsavedef, edit editf, 


editv, editp, 1 prettyprint, ес. Variable names are added to userwords at the same time as they are are 
added to spellings3. In addition, the variable lastword is always set to the last word added to 
userwords, i.e, the last function or variable referred to by the user, and the respelling of NIL is 


defined to be the value of lastword. Thus, if the user has just defined a function, he can then еди 


it by simply typing EDITF( ), or prettyprint it by typing PP(). 


Each of the above four spelling lists are divided into two sections separated by a special marker. 
The first section contains the "permanent" words; the second section contains the temporary words. 


New words are added to the corresponding spelling list at the front of its temporary section.” > (If | 


the word is already in the temporary section; it is moved to the front of that section; if the word is 
in the permanent section, no action is taken.) If the length of the temporary section then exceeds a 
specified number, the last (oldest) word in the temporary section is forgotten, i.e., deleted. This 
procedure prevents the spelling lists from becoming cluttered with unimportant words that are no 
longer being used, and thereby slowing down spelling correction time. Since the spelling corrector 
moves each word selected as a respelling to the front of its spelling list, the word is thereby 
moved into the permanent section. Thus once a word is misspelled and corrected, it is considered 
important and will never be forgotten. 


The maximum length of the temporary section for spellingsl, spellings2, spellings3 and userwords 
is given by the value of Zspellingsl, Zspellings2, #spellings3, and #userwords, initialized to 30, 
30, 30, and 60 respectively. Using these values, the average length of time to search a spelling list 
for one word is about 4 milliseconds.” 


GENERATORS FOR SPELLING CORRECTION 


For some applications, it is more convenient to generate candidates for a respelling one by one, 
rather than construct a complete list of all possible candidates, e.g., spelling correction involving a 
large directory of files, or a natural language data base. For these purposes, splst can be an array 
(of any sizc). The first element of this array is the generator function, which is called with the 
array itself as its argument. Thus the function can use the remainder of the array to store "state" 
information, e.g., the last position on a file, a pointer into a data structure, etc. The value returned 
by the function is the next candidate for respelling. If NIL is returned, the spelling "list" is 
considered to be exhausted, and the closest match is returned. If a candidate is found with no 
disagreements, it is returned immediately without waiting for the "list" to exhaust. 


splst can also be a generator, i.e. the value of the function generator (Section 12). Тһе generator 


splst will be started up whenever the spelling corrector needs the next candidate, and it should | 


return candidates via the function produce. For ските, 


23 Except that functions added to spellings] or spellings by lispx are always added to the end of the permanent section. 
24 Unless dontmovetopflg, one of the arguments to fixspell, is Т. 
25 


If the word is at the front of the spelling list, the time required is only 1 millisecond. If the word is not on the 
spelling list, i.e., if the entire list must be searched, the time is proportional to the length of the list; to search a 
spelling list of length 60 takes about 7 milliseconds. 
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+ [GENERATOR (MAPATOMS (FUNCTION (LAMBDA (X) (AND (FNTYP X) (PRODUCE X] 
+ could be used as a "spelling list" which effectively contains all functions in the system. 


17.4 ERROR CORRECTION 


As described in Section 16, whenever the interpreter encounters an atomic form with no binding, 
or a non-atomic form car of which is not a function or function object, it calls the function 
 faulteval. Similarly, when apply is given an undefined function, it calls faultapply. When DWIM 
is enabled, faulteval and faultapply are redefined to first call dwimblock, a part of the DWIM 
package. If the user aborts by typing control-E, or if he indicates disapproval of DWIM's intended 
correction by answering N as described on page 17.4, or if DWIM cannot decide how to fix the 
error, dwimblock returns М11,26 In this case, faulteval and faultapply proceed exactly as described 
in Section 16, by printing a U.B.A. or U.D. U.D.F. message, and going into a break if the 
requirements of breakcheck are met, otherwise unwinding to the last errorset. 


If DWIM can (and is allowed to) correct the error, dwimblock exits by performing reteval of the 
corrected form, as of the position of the call to faulteval or faultapply. Thus in the example at the 
beginning of the chapter, when DWIM determined that ITIMS was ITIMES misspelled, DWIM | 
called reteval with. (ITIMES N (FACCT 8SUB1 N)). Since the interpreter uses the value 
returned by faulteval exactly as though it were the value of the erroneous form, the computation. 
will thus proceed exactly as though no error had occurred. 


In addition to continuing the computation, DWIM also repairs the cause of the error whenever 
possible. Thus in the above example, DWIM also changed (with rplac a) the expression 
(ITIMS N (FACCT 8SUB1 N)) that caused the error. 


Error correction іп DWIM is divided into three categories: unbound atoms, undenned cars of 

form, and undefined function in apply. Assuming that the user approves if he is asked, the action 

taken by DWIM for the various types of errors in each of these categories is summarized below. 
Тһе protocol of DWIM’s interaction with the user has been described earlier. 


UNBOUND ATOMS 


1. If the first character of the unbound atom is ', DWIM assumes that the user (intentionally) 
typed 'atom for (QUOTE atom) and makes the appropriate change. No message is typed, and 
no approval requested. 


If the unbound atom is just " itself, DWIM assumes the user wants the next expression 
quoted, e.g.. (CONS X "(АВ C)) will be changed to (CONS X (QUOTE (A B С))). 
Again no message will be printed or approval asked. (If no expression follows the ', DWIM 


26 If the user answers with 7, (see page 17.4) dwimblock is exited by performing reteval[ F AULTEVAL ; SERO )1, 


. ће. an error is generated at the position of the call to faulteval. 
27 If the user's program had computed the form and called eval, e.g., performed (EVAL (LIST X Y)) and the value 
of x was a misspelled function; it would not be possible to repair the cause of the error, although DWIM could 
correct the misspelling each time it occurred. | 
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Error Correction 


gives up.)^? 


If CLISP (Section 23) is enabled, and the atom is part of a CLISP construct, the CLISP 
transformation is performed and the result returned, e.g., N-1 is transformed to (5081 №), 
(... FOO*3 ...) is transformed into (... (ФЕТО FOO 3) ...). 


If the atom contains an 8,29 DWIM assumes the 8 was intended to be a left parenthesis, and 


calls the editor to make appropriate repairs on the expression containing the atom. DWIM | 


assumes that the user did not notice the mistake, i.e., that the entire expression was affected 
by the missing left parenthesis. For example, if the user types . 

(SETQ X (LIST (CONS 8CAR Y) (CDR Z)) Y), the expression will be changed to 
(SETQ X (LIST (CONS (CAR Y) (CDR Z)) Y)). 


The 8 does not have to be the first character of the atom, е.р., DWIM will handle 


(CONS X8CAR Y) correctly. 


If the atom contains a 9°? DWIM assumes the 9 was intended to be a right parenthesis and 
operates as in number 3. 


If the atom begins with а 7, the 7 is treated as a ', eg. 7Ғ00 becomes "200, and then 
(QUOTE FOO). й 


If the atom is an еди command (а member of editcomsa), and the error occurred in type-in, 
the effect is the same as though the user typed EDITF(), followed by the atom, 1.е., DWIM 
assumes the user wants to be in the editor editing the last thing he referred to. Thus, if the 
user defines the function foo and then types P, he will see =FOO, followed by EDIT, followed 
by the printout associated with the execution of the P command, followed by *, at which 
point he can continue editing foo. | 


The expressions оп dwimuserforms are evaluated in the order that they appear, and if any 
returns a non-NIL value, this value is treated as the form to be used to continue the 
computation, and is evaluated and its value returned Бу DWIM. dwimuserforms is discussed 
further below. 


If the unbound atom occurs in a function, DWIM attempts spelling correction using as a 
spelling list the list of lambda and prog variables of the function. 


Since ' is normally defined as а read-macro character which converts ' FOO to (QUOTE ЕОО) оп input, РУМ 
will not see the ' in the case of expressions that are typed-in. 


actually the value of Iparkey, initially 8. See footnote on page 17.5. 


actually the value of rparkcy, initially 9. бес footnote on page 17.5, 
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_ If the unbound atom БЕС ей іп а type-in to а break, DWIM attempts spelling correction 


d the lambda and prog variables of the broken function. 


10. Otherwise, DWIM attempts spelling correction "T spellings3. 


If all fail, DWIM gives up. 


1. 
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UNDEFINED САН ОҒ FORM 


If car of the form is T, DWIM assumes a misplaced T clause and epee as described on 
page ре 17.5. 


If са of Ше form is F/L, DWIM changes the F/L to 
FUNCTION(LAMBDA, e.g., (FZL (Y) (PRINT (CAR Y))). is 2 changed to 
(FUNCTION (LAMBDA (Y) (PRINT (CAR Ү))). No message is printed and no € 
requested. If the user omits Ше variable list, DWIM supplies (X), 

(F/L (PRINT (CAR X))) becomes (FUNCTION (LAMBDA (X) (PRINT (CAR 0))- 
DWIM determines that the user has supplied the variable list when more than one expression 
follows F/L, car of the first expression is not the name of a function, and every element іп 
the first expression is atomic. For example, DWIM will supply (X) when correcting 
(F/L (PRINT (CDR X)) (PRINT (CAR X))). 


If car of the form is IF, or one of the CLISP iterative statement operators, e.g., FOR, 


. WHILE, DO et al, or FETCH, REPLACE, MATCH, etc., the indicated transformation is 


performed, and the result returned as the corrected form. 


If car of the form has a function definition, DWIM attempts spelling correction on car of the 
definition using as spelling list the value of lambdasplst, initially (LAMBDA NLAMBDA ).32 


If car of the form has an EXPR or CODE property, DWIM prints car of the form, юше by 
'UNSAVED"', performs an unsavedef, and continues. No approval is is requested. 


If car of the form has a property FILEDEF,? the definition is to be found on a file. If the 


This transformation is keyed by putting on the property list of car of the form, e.g. IF, WHILE, FETCH, under the 
property CLISPWORD, a list car of which is the atom IFWORD, FORWORD, RECORDWORD, etc. Any other value for 
car of this property is simply applied to the faulty form, and the value rcturned used as the corrected form. This 
provides a way of defining new transformations keyed by car of the form without having to use the more general 
dwimuserforms mechanism. 


The user may wish to add to lambdasplst if he elects to define new "function types" via an appropriate 
dwimuscrforms entry. For example, the QLAMBDAs of SRI's QLISP are handled in this way. 


except when dwimifying. 
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Error Correction 


value of the property is atomic, the entire file is to be loaded. If a list, car is the name of the 
file and cdr Ше relevant functions, and loadfns will be used. For both cases, ldflg will be 
SYSLOAD (see Section 14). DWIM uses findfile (described later), so that the file can be on 
any of the directories on directories, initially (NIL NEWLISP LISP LISPUSERS). If the 
file is found, DWIM types "SHALL I LOAD" followed by the file name or list of functions. 
If the user approves, DWIM loads the function(s) or file, and continues the computation. 


If CLISP is enabled, and car of the form is part of a CLISP construct, the indicated. 


transformation is performed, e.g., (МеМ-1) becomes (SETQ М (5081 М) ) s 


ЛЕ car of the form contains ап 8, DWIM assumes a left parenthesis was intended | 
ер. (CONS8CAR X). 


If car of the form contains а 9, DWIM assumes а right parenthesis was intended. 


If car of the form is a list, DWIM attempts spelling correction on caar of the form using 


lambdasplst as spelling list. If successful, DWIM returns the corrected expression itself. 


If car of the form is a small number, and the error occurred. in type-in, РУМ assumes Ше 
form is really an edit command and operates as described in case 6 of unbound atoms. 


If car of the form is an edit command (a member of editcomsl), DWIM operates as in 11. | 


The expressions оп dwimuserforms are evaluated in the order they appear, and if any returns 
а non-NIL value, this value is treated as the corrected form, i.e. it is evaluated and DWIM 
returns its value. 


Otherwise, DWIM attempts spelling correction using spellings2 as the spelling list. When 
dwimifying, DWIM also attemps spelling correction on function names not defined but 
previously encountered, using nofixfnslst as a spelling list. 


If all fail, DWIM gives up. 


UNDEFINED FUNCTION IN APPLY 


l. 


If the function has a definition, DWIM attempts spelling correction on car of the definition 
using lambdasplst as spclling list. 


If the function has ап EXPR or CODE property, DWIM prints its name followed бу 
'UNSAVED' , performs an unsavedef and continues. No approval is requested. 
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3. If the function has a property FILEDEF, DWIM proceeds as in case 6 of undefined car of 
form. 


4. If the error resulted from type-in, апа CLISP is enabled, and the function name contains a — 
CLISP operator, DWIM performs the indicated transformation, e.g., the user types 
FOO+( APPEND FIE FUM). | | | 


5. г Ше function. name contains an 8, DWIM assumes a left parenthesis was tended: ер. 
EDIT8F00]. 


6. If the "function" is a 15, DWIM attempts spelling correction on car of the dist using 
lambdasplst as spelling list. | 


7. If the function is a number and Фе error occurred in type-in, DWIM assumes the function is 
an edit command, and operates as described in case 6 of unbound atoms, е. 8. the user types | 
(on one line) 3 -lP. 


8. If the function is the name of an edit command (on either editcomsa : Or editcomsl ) DWIM 
Operates as in 7, е. eB. user types F COND. | 


9. The expressions оп dwimuserforms are evaluated in the order they appear, and if any returns 
a non-NIL value, this value is treated as the function used to continue the computation, i.e., „it 
will be applied to its arguments. | 


10. Otherwise DWIM attempts spelling correction using spellings] as the spelling list, 


11. Otherwise ПАЛМ attempts spelling correction using spellings2 as the spelling list. 


If all fail, DWIM gives up. 


17.5 DWIMUSERFORMS 


Dwimuserforms provides a convenient way of adding to the transformations that DWIM performs, 
e.g., the user might want to change atoms of the form $X to (QA4LOOKUP X). DWIM will 
evaluate each expression on dwimuscrforms in the order they appear before attempting spelling 


correction, but afler performing its other transformations, e.g., F/L, 8, 9, CLISP, ск. If any 


expression returns a non-NIL value, this value is treated as a form to be evaluated, and is 
cvaluated and the resulting value returned as the value of faulteval, or, in the case of an undefined 
function in apply, this valuc is treated as a function to be applied to faultargs, and the resulting 
value is returned as the value of faultapply. Otherwise, if all return NIL, DWIM proceeds as when 
dwimuserforms = NIL, and attempts spelling correction. Note that in the event that an expression 
on dwimuscrforms is to handle the correction, it is also responsible for any modifications to the 
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original expression,*4 i.e., DWIM simply takes its value and returns it. 


In order for an expression on dwimuserforms to be able to be effective, it needs to know various 
things about the context of the error. ‘Therefore, several of DWIM’s internal variables have been 
made SPECVARS (sce Section 18) and are therefore "visible" to dwimuserforms. Below are a list 
of those variables that may be useful. | | 


faultx | for unbound atoms and undefined саг of form, faultx is the atom or 
form. For undefined functions in apply, faultx is th is the name of the 
function. 


faultargs for undefined functions in apply, faultargs is the list of arguments. 
faultargs may be modified or reset by expressions on 
dwimuserforms. 


faultapply flg is T for undefined functions in apply. (Since faultargs may be NIL, 
faultapplyflg is necessary to distinguish between unbound atoms 
and undefined function in apply, since faultx is atomic in both 
cases). The value of faultapplyflg after an expression on 
dwimuserforms returns a non-NIL value determines how the latter 
value is to be treated. Thus, following an undefined function in 
apply, ie. when faultapplyflg is Т, an expression on dwimuserforms 
can construct and return an expression to be treated as a form to 
be evaluated, rather than a function to be applied, by first setting 


faultapplyflg to NIL. 


tail for unbound errors, tail is the tail car of which is the unbound 
atom. Thus dwimuserfn can replace the atom by another 
expression by performing (/RPLACA TAIL expr) | 


parent | for unbound atom errors, par ent is the form in which the unbound 
atom appears, i.e., tail is a tail of parent. | 


| type-in? true if error occurred in type-in. 

faultfn | | name of function in which error occurred. (faultfn is TYPE-IN 
when the error occurred in type-in, and EVAL or APPLY when the 
error occurred under an explicit call to EVAL or APPLY). 


dwimifyflg true if error was encountered during dwimifying as opposed to 
during running the program. 


expr definition of faultfn, or argument to eval, i.e., the superform in 
which the error occurs. 


The initial value of dwimuserforms is ((MACROTRAN) (DWIMLOADFNS?)). macrotran is a 
package for running interpreted programs containing assemble statements or calls to "functions" 


34 


i.e. dwimuscrforms should make the transformation permanent, either by associating it with faultx via clisptran, or by 
physically smashing faultx. 
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defined only by MACRO properties. It is described in Section 18. dwimloadfns? is a package for 
automatically loading functions from files. If dwimloadfnsflg is T (its initial value), and car of the 
form is the name of a function, and the function is contained on a file that has been noticed by the 
file package, the function is loaded, and the computation continues. | 


17.6 SPELLING CORRECTOR ALGORITHM 


The basic philosophy of DWIM spelling correction is to count the number of disagreements 
between two words, and use this number divided by the length of the longer of the two words as a 
measure of their relative disagreement. One minus this number is then the relative agreement or 
closeness. For example, CONS and CONX differ only in their last character. Such substitution 
errors count as one disagreement, so that the two words аге in 75% agreement. Most calls (о the 
spelling corrector specify a relative agreement of 70,35 36 so that a single substitution error is 
permitted in words of four characters or longer. However, spelling correction on shorter words is 
possible since certain types of differences such as single transpositions are. not counted as 
disagreements. For example, AND and NAD have a relative agreement of 100. | 


The central function of. the spelling corrector is chooz. chooz takes as arguments: a "word, a 
spelling list, a minimum relative agreement, and an optional | functional argument, xword, splst, rel, 


and fn respectively. 


chooz proceeds down splst examining each word. Words not satisfying fn, or those obviously too 
long or too short to be sufficiently close to xword are immediately rejected. For example, if 
ге1=70, and xword is 5 characters long, words longer than 7 characters will be гејес!ед 38 


If tword, the current word оп splst, is not rejected, chooz computes the number of disagreements 
between it and xword by с calling a subfunction, skor. 


skor aperies by scanning both words from left to right one character at a time.3? Characters are 


considered to agree if they are the same characters; or appear on the same teletype key (i.e., a shift 
mistake), for example, * agrees with :, 1 with 1,4 ° etc.; or if the character in xword is a lower case | 


Integers between 0 and 100 are used instead of numbers between 0 and 1 in order to avoid floating point arithmetic. 
36 Calls to the spelling corrector from DWIM use the value of fixspellrel, which is initially 70. Note that by setting 
fixspelirel to 100, only spelling corrections with "zero" mistakes, will be considered, e.g. transpositions, doubl 
characters, etc. as described below. | | 


31 f= NIL is equivalent to fn - (LAMBDA NIL T). 
38 Special treatment is necessary for words shorter than xword, since doubled letters are not counted as disagreements, | 
For example, CONNSSS and CONS have a relative agreement of 100. (Certain teletype diseases actually produce this 
‘sort of stuttering.) chooz handles this by counting the number of doubled characters in xword before it begins 
scanning splst, and taking this into account when deciding whether to reject shorter words. 


3) skor actually operates on the list of character codes for each word. This list is computed by chooz before calling skor 
using dchcon, so that no storage is used by the entire spelling correction process. 


For users on model 33 telctypes, as indicated by the value of model33flg being T, @ and P appear on the same key, 
as do L and /, М and L, and О and «, and DWIM will proceed accordingly. The initial value for model33flg is NIL. 
Certain other terminals, e.g., Anderson Jacobs terminal, have keyboard layouts similar to the тойс] 33, i.e., N on 
same key as 1, etc. In this case, the user might also want to set model33flg to T. 
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version of the character in tword. Characters that agree are discarded, and the skoring continues 
on the rest of the characters in xword and tword. j | 


ТЕ the first character in xword and tword do not agree, skor checks to see if either character is the 
Same а5 опе previously encountered, and not accounted-for at that time. (In other words, 
transpositions are not handled by lookahead, but by lookback.) A displacement of two or fewer 


positions is counted as a tranposition; a displacement by more than two positions is counted as a | 
disagreement. In either case, both characters are now considered as accounted for and are 


discarded, and skoring continues. 


If the first character in xword and tword do not agree, and neither agree with previously 
unaccounted-for characters, and tword has more characters remaining than xword, skor removes 
and saves the first character of tword, and continues by comparing the rest of tword with xword as 
described above. If tword has the same or fewer characters remaining than xword, the procedure i 15 


the same except that the character is removed from xword.*! In this case, a га special check is first- 


made to see if that character is equal to the previous character in xword, or to the next character in 
xword, i.e., a double character typo, and if so, the character is considered accounted- tor, and not 
counted as a disagreement. 


When skor has finished processing both xword and tword in this fashion, the value of skor is the 
number of unaccounted-for characters, plus the number of disagreements, plus the number of 
tranpositions, with two qualifications: (1) if both xword and tword have a character unaccounted-for 
in the same position, the two characters are counted only once, i.e, substitution errors count as 
only one disagreement, not two; and (2) if there are no unaccounted-for characters and no 
disagreements, transpositions are not counted. „ТАБ permits spelling correction on very short 
words, such as edit commands, e.g., XRT- XTR.A 


17.7 DWIM FUNCTIONS AND VARIABLES 


dwim[x] ши If x=NIL, disables DWIM; value is NIL. If x=C, enables DWIM 


in cautious mode; value is CAUTIOUS. If xz T, enables DWIM in 
trusting mode; value is TRUSTING. For all other values of x, 
generates an error. 


dwimify[x ;quietflg] x is a form or the name of a function. dwimify performs all 
corrections and transformations that would occur if x were actually 
run, and prints the result unless quietflg = T. dwimify is undoable. 


4l Whenever more than two characters in either xword or tword are unaccounted for, skoring is aborted, ie, xword 
and tword are considered to disagree, 

42 In this case, the "length" of xword is also decremented. Otherwise making xword sufficiently long by adding double | 
characters would make it be arbitrarily close to tword, е.р., XXXXXX would correct to PP. 
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with fastypeflg — T, only 60% with fastypeflg - NIL. The rationale behind this is that transpositions are much more 
common for fast typists, and should not be counted as disagreements, whereas more deliberate typists are not as 
likcly to combine tranpositions and other mistakes in a single word, and therefore can use more conservative metric. 
fastypeflg is initially NIL, 
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Transpositions are also not counted when fastypeflg=T, for example, IPULX and IPLUS will be іп 80% agreement | 


DW | 


addspell[x;splst;n] | 
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edit macro. dwimifies current expression. 


Adds x to one of the four spelling lists as follows: 

If splst=NIL, adds x to userwords and to spellings2. Used by 
defineq. 

If splst=0, adds x to userwords. Used by load when loading е exprs 
to property lists. 

If splst=1, adds x to spellings] (at end of permanent section). 
Used by lispx. | 

If splst=2, adds x to spellings2 (at end of permanent section). 


| Used b by lispx. 


If splst —3, adds x to userwords and spellings3. 


splst can also be a spelling list, in which case n is the (optional) 
еп of the temporary section. 


addspell sets lastword to x when splst= NI IL, 0 or 3. | 


If x is not a literal atom, addspell takes no action. 


+ Note that the various systems calls to addspell, e.g. from define, editf, load, etc, can all бе 
+ ‘suppressed by setting or binding addspellflg to NIL. 


 misspelled'lr word; rel;splst; flg;tail; fn] 


If xword=NI L or esc, | misspelled? Pade = followed by the value 
of lastword, and returns this as the respelling, without asking for 
approval. Otherwise, misspelled? checks to see if xword is really 
misspelled, i.e., if fn applied to xword is true, or xword is already 
contained on splst. In this case, misspelled? simply returns xword. · 
Otherwise misspelled? | | computes and returns 

fixspell[xword;rel;splst; flg;tail; fn]. | 


fixspelllxword: rel; эры; flg:tail;fn;tieflg; dontmovetopflg;-; -] 
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The value of fixspell is either the respelling of xword ог. NIL.4 
fixspell performs all of the interactions described earlier, acing 
requesting user approval if necessary. 


If xword=NIL or $ (<esc>), the respelling 5 the value of 
lastword, and no approval is requested. 


If xword contains lowercase characters, and the corresponding 


. If x is already on the spelling list, and in its temporary section, addspell moves x to the front of that section, See 


page 17.9 for complete description of algorithm for e pananing spelling lists. 
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If for some reason xword itself is on splst, then fixspell aborts and. calls error!. If there is a possibility that xword is 4 | 


· spelled correctly, misspelled? should be used instead of fixspell. 
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uppercase word is correct, ic. on 5 splst or satisfies fn, the uppercase 
word is returned and no interaction is performed. 


If rel = NIL, defaults to value of fixspellrel (initially 70). 


If flgzNIL, the correction is handled in type-in mode, i.e., 
approval is never requested, and xword is not typed. If flg=T, 
xword is typed (before the =) and approval is requested if 
арргоуейр< T. If flg- NO-MESSAGE, the correction is returned 
with no further processing. 46 


If tail is not NIL, and the correction is successful, car of tail is 
replaced by the respelling (using /rplac а). In addition, ‚ fixspell v will 
correct misspellings caused by running two words together." In this 
case, car Of tail is replaced by the two words, and the value of 
fixspell is the first one. For example, if fixspell is called to correct | 
the edit command (MOVE TO AFTERCOND 3 2) pr | 
(ай = (AFTERCOND 3 2), (ай would Бе changed 
(AFTER COND 2 3), and fixspell would return AFTER Gi 
to user approval where necessary). 


If ticflg=NIL and a tie occurs, i.e., more than one word on splst is 
found with the same degree of “closeness”, fixspell returns NIL, 
ie. no correction. If пейр- PICKONE and a tie occurs, the first 
word is taken as the correct spelling. If tieflg=LIST, the value of 
fixspell is a list of the respellings (even if there is only one), and 
fixspell will not perform any interaction with the user, nor modify 
tail, the idea being that the calling program will handle those tasks. 
Similarly, if ticflg=EVERYTHING, a list of all candidates whose | 
degree of closeness is above rel will be returned, regardless of 
whether some are better than others. No interaction will ђе 
performed. 


If dontmovetopflg — T and a correction occurs, it will not be moved 
to the front of the spelling list. | 


The time required for a call to fixspell with a spelling list of length 60 when the entire list must be 
searched is .5 seconds. If fixspell determines that the first word on the spelling list is the respelling 

and does not need to search any further, the time required is .02 seconds. In other words, the _ 
time required is proportional to the number of words with which xword is compared, with the time 


46 In this case, a run-on correction will be returned as a dotted pair of the two parts of the word, and a synonym 
correction as a list of the form (wordl word2), where wordl is (the corrected version of) xword, and word2 is the 
synonym. Note that the effect of the function chooz (documented in previous manuals but no longer available) can 
be obtained by calling fixspell with Пр = NO-MESSAGE. 

^! шіні case, user approval is always requested. In addition, if the first word contains either fewer than 3 characters, 
or fewer characters than the second word, the default will be М. "Кип-оп" spelling corrections can be suppressed by 
setting the variable runonflg to NIL (initially T). 
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If tail - T, fixspcll will also perform run-on corrections, rouming a dotted pair of the two words іп the event the 
correction is of this type. 
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. for one comparison, i.e., one call to skor takes roughly .01 seconds ше slightly with the number 


of characters in the words being. compared). 


душ — 


fixspellrel 


fixspelldefault 


dwimwait 


addspellflg 


nospellflg 


runonflg 


dwimuserforms 


dwimloadfnsflg 


if NI L, suppresses all dwim operations. 


default for rel on calls to fixspell when rel МП. (most system calls 
to fixspell specify ЕВЕ Initial value is 70. 


if approval is requested for a sbetlihe correction, and user does not 
respond, defaults to value of  fixspelldefault, initially У. 
fixspelldefault is rebound to N when dwimifying. | 


number of seconds before dwim assumes the user is not going to 
repond to a question and uses the default response; 


if NIL, suppresses calls to addspell. Initially T. 


if T, | suppresses all spelling correction. If some other non-NIL 


. value, Suppresses | spelling correction in programs but not type-in. 


nospellflg is SN NIL. It is rebound to T when compiling from 
a file. | 


if NIL, suppresses run-on spelling corrections. Initialy Т 


allows user to specify his own corrections or transformations. Initial 
value is ((MACROTRAN) (DWIMLOADFNS?)). See page 17.14. 


if T, tells DWIM when it encounters a call to an undefined function 
contained on a file that has been noticed by the file package, to 
simply load the function. dwimloadfnsflg is initially T. See page 
17.16. | 


fncheck[fn;noerrorflg; 2 propfig;tail] 


49 


place when dwimflg=T, 


РУМ. . 


The task of fncheck is to check whether fn is the name of a 
function and if not, to correct its spelling.4? If fn is the name of a 
function or spelling correction is successful, _ fncheck adds Ше 
(corrected) name of the function to userwords using addspell, and 
returns it as its value. | 


Since fncheck is called by many low level functions such as arglist, unsavedef, etc., spelling correction only takes 
so that these functions can operate in a small Interlisp system which does not contain 
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_ noerrorflg informs fncheck whether or not the calling function 


wants to handle the unsuccessful case: if nocrrorflg is T, fncheck 


simply returns NIL, otherwise it prints fn NOT A FUNCTION ON and 
generates a non-breaking error. — 


If fn does not have a definition, but does have an EXPR property, 


then spelling correction is not attempted. Instead, if propflg— T, fn 
is considered to be the name of a function, and is returned. If 
propflg = NIL, fn is not considered to be the name of a function, 


and NIL is returned or an error generated, depending on the value | 


. of noerrorflg. 


fncheck calls misspelled? to perform spelling correction, SO that if 


fn=NIL, the value of lastword will be returned.  spellflg 
corresponds to misspelled?'s fourth argument, Пе. If spellflg- T, 
approval will be asked if DWIM was enabled in CAUTIOUS mode, 
ie. if approveflg— T. tail corresponds to the fifth argument to 
misspelled?. | | BE di 


fncheck is currently used by arglist, unsavedef, prettyprint, break0, breakin, advise, ‚ calls, and edita. 


For example, breakO calls fncheck with noerrorflg=T since if fnc fncheck can cannot ot produce a function, | 


break0 wants to define a dummy опе. calls however calls fncheck w with noerrorflg = NIL, since it 
cannot operate without a function. | 


Many other system functions call misspelled? or fixspell directly. For example, break] calls fixspell 
on unrecognized atomic inputs before attempting to evaluate them, using as a spelling list a list of 
all break commands. Similarly, lispx calls fixspell on atomic inputs using a list of all lispx 


commands. When unbrcak is given the name of a function that is not broken, it calls fixspell with. 


two different spelling lists, first with brokenfns, and if that fails, with userwords. makefile calls 
misspelled? using filelst as a spelling list. Finally, load, bcompl, brecompile, tcompl, and nd recompile 
all call misspelled? if their input file(s) won't open. 


spellfile[file;noprintflg;nsflg] ІҒ file does not have a directory field, spellfile looks on the 
directories given by the value of directories, initially (NIL LISP). 
(NIL corresponds to login directory. This correction will not 
require user approval, (but spellfile will indicate the correction in 
the usual way, by printing — followed by the new file name). 
Otherwise, зрей е attempts spelling correction against the files in 
the directory. 1n this case, user approval will be requested (except 


if nprintflg = T, see below). Value is corrected file, if any, otherwise | 


NIL. 


If noprintflg = T, spellfile does not do any printing, nor ask for 
approval. | 


If nsflg=T (ог nospellflg = T), no spelling correction is attempted, 


though searching through directories will still be performed. 


findfilc[file;nsflg] If file is not the name of a file, calls spellfile specifying no 


interaction ог printing, іе  findfile is defined as 
(OR (INFILEP FILE) (SPELLFILE FILE T NSFLG)). 
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17. 8 ASKUSER 


DWIM. the compiler, the editor, and many other system packages all use РЕН ап extremely 
general user interaction package, for their interactions with the user at the terminal. askuser takes - 
as its principal argument а keylst which is used to drive the interaction. keylst specifies what the 
user can type at any given point, how askuser should respond to the various inputs, what value 
should be returned by askuser, and is also used to present the user at any given point with a list of 
the possible responses. а5Кивсг also takes other arguments which permit specifying а wait time, a 
default value, a message to be printed on entry, a flag indicating whether or not typeahead is to be 
permitted, a flag indicating whether the transaction is to be stored on the history list (Section 22), a 
default set of options, and an (optional) input file/string. 


STARTUP PROTOCOL 


Interlisp permits and encourages the user to typeahead; in actual practice, the user frequently does 
this. This presents a problem for askuser: when askuser is entered and there has been typeahead, | 
was the input intended for askuser, or was the interaction unanticipated, and the user simply typing 
ahead to some other program, e.g. the programmer’s assistant? Even where there was no typeahead, | 
ie. the user starts typing after the call to askuser, the question remains of whether the user had | 
time to see the message from askuser and react to it, or simply began typing ahead at an 
inauspicious moment. Thus, what is needed is an interlock mechanism which warns the user to 
Stop typing, gives him a chance to respond to the warning, and then allows him to begin typing to _ 
askuser. | 


. Therefore, when askuser is first entered, and the interaction is ‚ {о take рас with a ната and 
· typeahead to askuser is г is not permitted, the following protocol is observed: 


(1) If there is typeahead, askuser clears and saves the input buffers’? and rings the bell to warn 
the user to stop typing. 


(2) If mess, the message to be printed on entry, is not NI 1 (Ше typical case), askuser then prints - 
| mess ss if it is a string, otherwise car of mess, if mess is a list. 


(3) After printing mess or car of mess, askuser waits until the output has actually been printed on 
the terminal to make sure that the user has actually had a chance to see the output. This also 
give the user a chance to react. askuser then checks to see if anything additional has been 
typed in the intervening period since it first warned the user in (1). If something has been | 
typed, askuser clears it out and again rings the bell. This latter material, i.e., that typed 
between the entry to askuscr and this point, is discarded and will not be restored since it is 
not certain whether the user simply reacted quickly to the first warning (bell) and this input is 
intended for askuser, or whether the user was in the process of typing ahead when the call to- 
askuser occurred, and did not stop typing at the first warning, and therefore this input isa 
continuation of input intended for another program. 


Anything typed after (3) is considered to be intended for askuser, i.e., once the user sees mess or 
car of mess, һе is free to respond. For схатріс, UNDO (Section 22) calls askuser when the 


50 The buffers will be restored when askuser completes operation and returns. 
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number of undosaves are exceeded for an event with mess = (LIST #UNDOSAVES "undosaves, 
continue saving"). Thus, the user can type a response as soon as the value of #undosaves is 
typed. 


(4) askuser then types the rest of mess, if any, and 


(5) then goes into a wait loop until something is typed. If wait, the wait time, is not NIL, and 
nothing is typed in wait seconds, askuser will type " " and treat the elements of default, the 
default value, as a list of characters, and begin processing them exactly as though they they had 
been typed. If the user does type anything within wait seconds, he can then wait as long as he 
likes, е, once something has been typed, askuser r will not use the default value specified in 
делш? 


If the calling program knows that the user is expecting an interaction with askuser, e.g. another 
interaction preceded this one, it can specify in the call to askuser that typeahead 5 is permitted, Іп 
this case, askuser simply notes whether there is any typeahead, then prints mess and goes into a 
wait loop as as described above. 


Finally, if the interaction is not with the terminal, i.e., the optional input file/string is specified, 
askuser simply prints mess and begins reading from the file/ string. 


OPERATION 


All input operations are executed with a terminal table? in which (1) control[T] has been executed, 
so that askuser can interact with the user after each character is typed; and (2) echomode[NIL] has 
been executed, so that askuser can decide after it reads a character whether or not the character = 
should be echoed, and with what, e.g. unacceptable inputs are never echoed. 


As each character is typed, it is matched against keylst, and appropriate echoing and/or prompting 
is performed. If the user types an unacceptable character, askuser simply rings the bell and allows 
him to try again. 


At any point, the user can type 9% and receive а list of acceptable responses at that point 
(generated from keylst), ог type a control-a, control-q, control-x, or 461,55 which causes askuser to 
reinitialize, and start over. | У 


When an acceptable sequence is completed, askuser returns the indicated value. 


3 ү the user wants to consider his response for more than wait seconds, and does not want askuser to default, he can | 
type a carriage return or a space, which are ignored if they are not specified as шаны inputs by keylst (see 
below) and they are the first thing typed. | 

52 In this case, if the typeahead turns out to contain unacceptable input, askuser will assume that the typeahead was not 
intended for askuser, and will restore the typeahead when it completes operation and returns. 

53 The name of this terminal table is askuserttbl. 

54 Unless ? itself is an acceptable input, i.e., it matches one of the keys on keylst. 

55 


Unless these characters are acceptable Шри. and assuming del is not an interrupt und so that it is, in ‘fact, seen 
by askuser. 
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FORMAT OF KEYLST - 


 keylst is a list of elements of the form (key promptstring . options), where key is an atom or a 


string (equivalent), promptstring is an atom or a string, and options a list of options in property list 


format. The following options are recognized and explained below: KEY LST , CONFIRMFLG, 


PROMPTCONFIRMFLG, NOCASEFLG, RETURN, . EXPLAINSTRING, | NOECHOFLG, 
KEYSTRING, PROMPTON, COMPLETEON, AUTOCOMPLETEFLG. If an option is specified іп 


options, the value of the option is the next element. Otherwise, if the option is specified in — 


optionslst (the seventh argument to askuser) its value is the next element on optionslst. Thus, - 


. optionslst can be used to provide default options for an entire keylst, rather than having to include 


+++ 


the option at each level. If an option does not appear on either options or г optionsist, its value is _ 
NIL. Жа” 


For convenience, an entry on keylst of the form бре. atom/string) с: сап Си 0:60 аѕ ап abbreviation 5 
for (key atom/string CONFIRMFLG Т), апа an entry of just the form key, i.e., a non-list, as an 
abbreviation for (key NIL CONFIRMFLG T). | 


As each character is и, it is matched against the currently active keys. A character matches a. key 


if it is the same character as that in the corresponding position in the key, or, if the character is an 


alphabetic character, if the characters are the same without regard for upper/lower case differences, 

ie. "А" matches "а" and vice versa?? In other words, if two characters have already been input 
and matched, the third character is matched with each active key by comparing it with the third 
character of that key. If the character matches with one or more of the keys, the entries on keylst 
corresponding to the remaining keys are discarded. If the character does not match with any of the 
keys, the character is not echoed, and a bell is rung instead. 


When a key is complete, promptstring 15 өтілді (NIL is equivalent to "" , the empty string, 1 ie, | 
nothing will be printed). Then, if the value of the CONFIRMFLG option is T, askuser waits for т. 
confirmation of the key by а 257 or space. Otherwise, the key does not require confirmation, — 


Then, if the value of the KEYLST option is not NIL, its value becomes the new keylst, and the 
process recurses. Otherwise, the key 15 a "leaf," i.e., it terminates a particular path through the 


original, top-level keylst, and askuser returns the result of packing all the keys that have been 
matched and completed along the way (unless the RETURN option is 5 used to specify some other 
value, as described below). 


For example, the following keylst is the default keylst, ie. is used when askuser is called with 
keyist = NIL: ((Y "es2") (N "ов")) 


This keylst specifies that if (as soon as) the user types Y (or y), askuser echoes with Y, prompts 
with "es 2", and returns Y as its value. Similarly, if the user types М, askuser echoes Ше М, prompts 
with "o2", and returns N. If the user types ?, askuser prints: | 


Yes 


No 


to indicate his possible responses. АП other inputs are unacceptable, and askuser will fing the bell | 
and not echo or print anything. 


56 Unless the NOCASEFLG option (page 17.27) is Т. 


3 — Q2 is used throughout the discussion to denote carriage return. 
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Here is a more complicated example, the keylst used for the ‘compiler questions (section 182): | 


((5Т "оге and redefine " KEYLST С" (ғ. А "orget exprs")) | 


(5. "ame as last time") 
(Е. "File only") 
(T . "o terminal") 


(Y : "еѕ") 


(М . "о")) 


When askuser is called with this keylst, and the user types ап 5, two keys are matched: ST and 5. 
The user can then type a T, which matches only the ST key, or confirm the S key by typing a 2 or 
space. If the user confirms the S key, askuser prompts with “ame as last time", and returns 5. 
as its value. (Note that the confirming character is not included in the value.) If the user types aT, 
askuser prompts with "ore and redefine", and makes ("" (F . "orget exprs")) be the _ 
new keylst, and waits for more input. The user can then type an Е, or confirm the "" (which | 


essentially starts out with all of its characters matched). If he confirms the "" , askuser. returns ST | 


as its value the result of packing ST and "". If he types Е, askuser prompts. apts with ' ‘orget 
exprs", and waits for confirmation again. If the user then confirms, a askuser returns ST F, the 
result of packing ST and F. | ти | 


As mentioned earlier, at any point the user can type a ? and be prompted with the possible 
responses. For example, if the user types S and then ? 24 askuser will Piper Е T | 


STore and redefine Forget exprs 
STore and redefine | 
Same as last time 


COMPLETING A KEY 


The decision about when a key is complete is more complicated than simply whether or not all of 

its characters have been matched. In the example above, all of the characters in the S key are 
matched as soon as the S has been typed, but until the next character is typed, askuser does not 
know whether the S completes the S key, or is simply the first character in the ST key. T key. Therefore, | 
а key is considered to be ape when: | 


(1) АП of its characters have been matched and it is the only key left, 1.е., there are по other keys 
for which this key is a ЭБШ, or 

(2) All of its characters have been matched and a confirming character is typed; or 

(3) АП of its characters Bay been matched, and the value of the CONFIRMFLG option is NIL, 
and the value of the KEYLST option is not NIL, and the next character matches one of the 


keys on the value of the KEYLST option; or 
(4) There is only one key left and a confirming character is typed. 
Note that if the value of CONFIRMFLG is T, the key still has to bc бейнені regardless. of 


whether or not it is complete. For example, if the first entry in the above example were instead - 
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(ST "ore and redefine " CONFIRMFLG Т KEYLST ("" (Е . "orget exprs")), and 
the user wanted to specify the STF path, he would have to type ST, then confirm before typing F, 
even though the ST completed the ST key by the rule in case (1). However, he would be а лем 
with "ore and redefine" as soon as he typed the T, and completed the ST key. | 


Case (2) says that confirmation can be used to complete a key in the case where it is a “substring of 
another key, even where the value of CONFIRMFLG is NIL. In this case, the confirming character 
doubles as both an indicator that the key is complete, and also to confirm it, if пошу This 
situation corresponds to typing 52 in the above example. | 


Case (3) says that if there were anotner entry whose key was STX in the above cunis SO that 
after the user typed ST, two keys, ST and STX, were still active, then typing F would complete the - 
ST key, because F matches the (F . "orget exprs") entry on the value of the KEYLST 
option of the ST entry. In this case, "оге and redefine” would be printed before the F was 

echoed. | | | : T es 


Finally, case (4) says that the user can use confirmation to specify completion when only one key is 0 


left, even when all of its characters have not been matched. For example, if the first key in the 
. above example were STORE, the user could type ST and then confirm, and ORE would be echoed, 


followed by whatever prompting was specified. In this case, the confirming. character also confirms 
the key if а so that no further action is required, even when the bas of CONFIRM d LG is 


Case (4) permits the user not to have to type every character i in a key when the та і5 Ше only one 
left. Even when there are several active keys, the user can type type $ (the ESC key, or on some 


terminals, the key labelled ALT) to specify the next n > 0 common characters among the currently. - | 


active keys. The effect is exactly the same as though these characters had been typed. If there are 
no common characters in the active keys at that point, ie. n=0, the $ is treated as an incorrect 


input, and the bell is rung. For example, if keylst is (CLISPFLG CLISPIFYPACKFLG | | 


CLISPIFTRANFLG), and the user types С followed by таа askuser will supply the |, I, 8, and Р. 
The user can then type F followed by 2 or space to complete and and confirm CLISPFLG, as per case 
(4), or type I, followed by $, and askuser will supply the F, etc. Note that the characters supplied 
_ do not have to correspond to a terminal segment of any of the keys. Note also that the $ does not 
confirm the key, although it may complete it in the case that there is only one key active. 


If the user types a confirming character when several keys are left, the next 120 common 
characters are still supplied, the same as with 8. However, askuser assumes the intent was to 
complete a key, i.e., case (4) is being invoked. Therefore, after supplying the next n characters, the 
bell is rung to indicate that the operation was not completed. In other words, typing a confirming 
character has the same effect as typing an $ in that the next n common characters are supplied. 
Then, if there is only one key left, the key is complete (case 4) and confirmation is по! required. If 
the key is not the only key left, the bell is rung. | | 


OPTIONS 
KEYLST | | When a key is complete, if the value of the KEYLST option is not 
| NIL, this value becomes the new kcylst and the process recurses. 
Otherwise, the key terminates a path through the original, top-level 
kcylst, and askuser returns the indicated value. | : 
 CONFIRMFLG If T, (he key must be confirmed with either a 2 or a space. If the | 


valuc of CONFIRMFLG is a list, the ош EMT TM be | 
any member of the list. P | ENS 2% 
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If T, whenever confirmation is required, the user is prompted with 


the string ч (соппш) ". 


. 1f T, says do not. шт case independent matching on alphabetic 
characters. If NIL, do. perform case independent matching, ie. ' A m 
matches with ' a' and vice versa. | 


If non-NIL, eval of the value of the RETURN option is returned as 


the value of askuser. Note that different RETURN options can be | 


specified for different keys. The variable answer 15 bound in askuser 
to the list of keys that have been matched. In other words, RETURN 


does. 


If the value of the EXPLAINSTRING option is non-NIL, its value is 
printed when the user types a ?, rather than key + promptstring. 
EXPLAINSTRING enables more elaborate explanations. in response 


чо a ? than what the user sees when he is prompted as a result of 


simply completing keys. See example below. 


ТЕ non-N I L, characters: that are matched (on automatically supplied 


as a result of typing $ or confirming) are not echoed, nor is the 


+++ ++ 


(PACK ANSWER) would be equivalent to what askuser normally — 


confirming character, if any. The value of NOECHOF LG is | 


automatically NIL when askuser is reading from a file or string. 
The decision about whether or not to echo a character that matches 


several keys is determined by the value of the NOECHOF LG option ES 


for the first key. 


Example: one of the entries on the Кейн used Бу addtofiles (section 14) is: 


(1 "Nowhere?" NOECHOFLG T EXPLAINSTRING VUE * nownere, item is marked as 


а dummy2") 


When the user оре ане just prints "Момћеге»", i.e., the | is not echoed. If the user e 2% 


the explanation corresponding to this entry will be: 


1 - nowhere, item is marked as a dummy 


KEYSTRING | 


PROMPTON 


COMPLETEON 


If non-NIL, characters that are matched are echoed as though the _ 
value of KEYSTRING were used in place of the key. KEYSTRING _ 


is also used for computing the value returned. The main reason for 
this feature is to enable echoing in lowercase. | — 


If non-NIL, promptstring is printed only when the is is confirmed 
. with a member of the value of PROMPTON. See example below. __ 


When a confirming character is typed, the n characters that are 
automatically supplied, as specified in case (4), are echoed only 
when the key is confirmed with a member of the value of 
PROMPTON. | 


Тһе PROMPTON and GOMPEETEON Телу enable the uscr to construct a E which will o cause 
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askuser to emulate the action of the TENEX exec. The protocol followed by the TENEX exec is 
that the user can type as many characters as he likes in specifying a command. The command сап | 


be completed with a 2 or space, in which case no further output is forthcoming, or with a $, in. 


which case the rest of the characters in the. command are echoed, followed by some prompting - 


: information. The following keylst t would handle the TENEX COPY and CONNECT comands: 


 ((COPY " (FILE LIST) " PROMPTON ($) COMPLETEON (5) CONFIRMFLG ($)) 


т. d Ure ed à PROMETON ($) COMPLETEON ($) CONFIRMFLG ($))) 


AUTOCOMPLETEFLG “Ево хеше ор the Corr option is not NIL, askuser — 


will automatically supply unambiguous characters whenever it can, . 


i.e., askuser acts as though $ were typed after each character (except | | 
~ that it does not ring the bell if there are no а И 
| characters). - ue ^ 


MACROCHARS | vale is a list of dotted pairs of form Gunda: form). When | 


^. character is typed, and it does not match any of the current keys, | Е 


form is evaluated and. nothing else happens, ie. the matching >. 
process stays where it is. For example, ? could have been | 


implemented using this option. Essentially MACROCHARS provides | 


a read macro facility while inside of askuser (since askuser доев 
readc's, read macros defined via the readtable are never г invoked). 


EXPLAINDELIMITER value is what is printed to delimit explanation in response to ?. 
277% 4 | Initially "ә" put can be reset, € ial to", ", for more linear output. —.— 
SPECIAL KEYS . 

& can be used as a key to match with any single character, provided the character does not match 
with some other key at that level. For the purposes of echoing and returning a value, the effect is 


the same as though the character that were matched actually appeared as the кеу. 


$ (esc) сап be used as а key to match with the result of a single call to read. For example, if the 
first entry in the TENEX keylst above were: 


(COPY " (FILE LIST) " PROMPTON (5) COMPLETEON (5) CONFIRMFLG (5) 
KEYLST (($ NIL RETURN ANSWER))). 0 


then if the user typed COP(space)F002, (COPY F00) would be returned as the value of | 


askuser. One advantage of using $, rather than having the calling program perform the read, is that _ 


the call to read from inside askuser is errorset protected, so that the user can back out of this path- 
and reinitialize askuser, е. g. to change from a COPY command to a CONNECT command, simply зу 
typing control- E. | 


| $$. can be ued as a key to match with the result of a single call to readline. 


A list can be used as a key, in which case the list/form is evaluated and its value "matches" the 
key. This feature is provided primarily as an escape hatch for including arbitrary input operations 
as part of an askuser sequence. For cxample, the cffect of $$ could be achieved simply by using Є 
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(READLINE Т) asa key.-° 


"о" 


9.9 


essentially functions as a place marker. For ре, опе of the entries on the keylst used by 
addtofiles is: 


("" "File/list: " EXPLAINSTRING 
"a file name or name of a function list" KEYLST ($)) 


Thus, if the user types a character that does not match any of the other keys on the keylst, then. 


the character completes the "" key, by virtue of case (4), since the character wil] match with the 5 
in the inner keylst. askuser then prints "File/list: " before echoing the character, then calls 


read. The character will be read as part of the read. The value returned by askuser will be (һе 


value of the read. 


askuser[wait;default;mess;keylst;:typeahead;lispxprntflg;optionslst; file] 
wait is either NIL or a number (of seconds). default is a single 
character or a sequence (list) of characters to be used as the default 
inputs for the case when wait is not NIL and more than wait 
seconds elapse without any input. In this case, the character(s) from 
default are processed ica as though they had been typed, except 
that askuser first types "..." 


mess is the initial message to be printed by askuser, if any, and can 
be a string, or a list. In the latter case, each element of the list is 
printed, separated by spaces, and terminated with a " ? ". keylst 
and optionslst were described earlier. typeahead is T if the user is 
permitted to typeahead a response to askuser. NIL means any 
typeahead should be cleared and saved. lispxprntflg determines 
whether or not the interaction is to be recorded on the history list. 


file can be either NIL (in which case it is set to T), the name of a 


file, or a string.?? АП input operations take place from file until an 
unacceptable input is encountered, ie. one that does not conform 
to the protocol defined by keylst. At that point, file is set to T, 
default is set to NIL, the input buffer is cleared, and a bell | is rung. 
Unacceptable inputs are not echoed. 


The value of askuser is the result of packing all the keys that were 
matched, unless the RETURN option is specified (page 17.27). | 


таКеКеу151[15; defaultkey;lcaseflg] 


Ist is а list of atoms or strings. makekeylst returns an askuser keylst. 


which will permit the user to specify one of the elements on Ist by 


% Бог $. $$, or a list, if the last character read by the input operation is a separator, the character is treated as a 
confirming character for the key. However, if the last character is a break character, it will be matched against the 
next key. 

23 ү file is a string, and all of its characters are read before askuset finishes, file will be reset to T, and the interaction 


will continue with askuser reading from the terminal. 
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can be used as a key. Since it has no characters, all of its characters are automatically matched. 


+++ 


+++ 


++ + + + + ++ +++ 
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either typing enough characters to make the | choice unambiguous, | 
ог else typing à number between 1 and n, where n is the Meng ог. 
[st uM ја 


For eae if askuser is called with keylst = makekeylst{( CONNECT SUPPORT COMPILE ТЕ then | 
the user can type | C-O-N, 5, C-O-M, 1, 2, or 3 to indicate one of the three choices. | | 


case (but the value returned will still be one of the elements of Ist). 
If defaultkey is non-NIL, it will be the last key on the keylst. . 
Otherwise, a key which permits the user to indicate "No - none of 

the above” choices, in which case the value returned by askuser will | 
be NIL. 
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SECTION 18 
THE COMPILER AND ASSEMBLER! 


18.1 THE COMPILER 


The compiler is available in the standard Interlisp system. It may be used to compile individual 
functions as requested or all function definitions in a standard format LOAD file. The resulting 
code may be stored as it is compiled, so as to be available for immediate use, or it may be written 
onto a file for subsequent loading. „= | 


The most common way to use the compiler is to compile from a symbolic (prettydef) file, 


producing a corresponding file which contains a set of functions in compiled form which can be 
quickly loaded. An alternate way of using the compiler is to compile from functions already 
defined in the user’s Interlisp system. In_this case, the user has the option of specifying whether 
the code is to be saved on a file for subsequent loading, or the functions redefined, or both. In 
either case, the compiler will ask the user certain questions concerning the compilation. The first 
question is: 


LISTING? 


The answer to this question controls the generation of a listing and is explained in full below. 


However, for most applications, the user will want to answer this question with either ST or F, 
which will also specify an answer to the rest of the questions which would otherwise be asked. ST 
means the user wants the compiler to STore the new definitions; F means the user is only 
interested in compiling to a File, and no storing of definitions is performed. In both cases, the 
compiler will then ask the user one more question: | | 


ОЏТРЏТ FILE? 


to which the user can answer: 


N or NIL no output file. 

Y or YES user is then asked the name of the file. | 

File name file is opened if not already opened, and compiled code is written 
on the file. 


The Interlisp-10 compiler itself, i.e., the part that actually generates code, was written and documented by, and is the 
responsibility of А.К. Hartley. The user interfaces, i.e., tcompl, recompile, bcompl, and breconipile, were written by 
W. Тейсітап, 
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Example: 


<СОМРТИ Е ( (FACT РАСТ FACT2)) 
LISTING? ST 

OUTPUT FILE? FACT.COM 

(FACT COMPILING) 


(FACT REDEFINED)2 


(FACT2 REDEFINED) 
(FACT ЕАСТ1 FACT2) 


€ 


This process caused the functions FACT, ҒАСТ1, and ҒАСТ2 to be compie redefined, and the 
compiled definitions also written on the file FACT.COM for subsequent loading. 


18.2 COMPILER QUESTIONS 


The compiler uses the free variables lapflg, strf, svflg, Icfil and Istfil which determines various 
modes of operation. These variables are set by the answers to the "compset" questions. When any 
of the top level compiling functions are called, the function compset is called which asks a number 
of questions. Those that can be answered "yes" or "no" can be answered with YES, Y, or T for 
YES; and NO, N, or NIL for NO. The questions are: Ж | | 


1. LISTING? 
The answer to this question controls the generation of a listing. Possible answers are: 
1 Prints output of pass 1, the LAP macro code. 
2 Prints output of pass 2, the machine code. 
YES Prints output of both passes. 
NO X Prints no listings. 


Тһе variable lapflg is set to the answer. If the answer is affirmative, compset will type FILE: to 
allow the user to indicate where the output is to be written. The variable Istfil is set to the answer. 


There are three other possible answers to LISTING? - each of which specifies a complete mode for 
compiling. They are: 


S бате as last setting. 
F Compile to File (no definition of functions). 


ST  STore new definitions. 
STF STore new definitions, Forget exprs. 


compiler printout and error messages are explained in Section 18.18, page 18.33-36. 


The LAP and machine code are usually not of interest but can be helpful in debugging macros. 
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Compiler Questions 


Implicit in these three are the answers to the questions on disposition of compiled code and SEDES S, 
so questions 2 and 3 would not be asked if 1 were answered with S, F, ST, or STF. 


2; REDEFINE? 


YES Causes each function to be redefined as it is compiled. The compiled code is - 
stored and the function definition changed. The variable strf is set to Т. 


NO Causes faction definitions to remain unchanged. The variable strf is set to 
NIL. 


The answer ST or STF for the first question implies YES for this ыы F implies NO, and 5 
makes no change. 


3. SAVE EXPRS? 


If answered YES, svflg is set to T, and Ше exprs are saved on the property list of the function © 
name. Otherwise they are discarded. The answer ST for the first queshon implies YES for this 
question, F or STF implies NO, and S makes no change. 


4. OUTPUT FILE? 


If the compiled definitions are to be written for later loading, you should provide the name of a 
file on which you wish to save the code that is generated. If you answer T or TTY:, the output 
will be typed on the teletype (not particularly useful) If you answer N, NO, or NIL, output will 
not be done. If you answer Y or YES, you will be asked the name of the file. If the file named is 
already open, it will continue to be used. The free variable Icfil is set to the name of the file. 


Compiler output and error messages are further documented in Section 18.18. 


18.3 COMPILING NLAMBDAS 


When compiling the call to a function, the compiler must prepare the arguments to the function in 
one of three ways: 


| Evaluated (SUBR, SUBR*, EXPR, EXPR*, CEXPR, CEXPR*) 
2. Unevaluated, spread (FSUBR, FEXPR, CFEXPR) 
3. Unevaluated, not spread (FSUBR*, FEXPR*, CFEXPR*) 


In attempting to determine which of these three is appropriate, the compiler will first look for a 
definition among the functions in the file that is being compiled. If the function is not contained 
there, the compiler will look for other information which can be supplicd by the user by including 
nlambda nospread functions on the list nlama (for nlambda atoms), and including nlambda spread 
functions on the list пат! (for nlambda list), and including lambda functions on the list lams.* If 
the function is not contained in the file? or on the list шата, nlaml, or lams, the compiler will 


Including functions on lams is only necessary to override in-core nlambda definitions, since in the absence of other 
information, the compiler assumes the function is a lambda. 


The function can be defined anywhere in any of the files given as arguments to bcompl, tcompl, brecompile or 
recompile, 
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look for a current definition. If the function is defined, its function type is assumed to be the 
desired type. If it is not defined, the compiler assumes that the function is of type 0 or 1, 1.е., its 
arguments are to be evaluated.® 7 In other words, if there are type 2 or 3 functions called from the 
functions being compiled, and they are only defined in a separate file, they must be included on 


nlama ог nlaml, or the compiler will incorrectly assume that their arguments are to be evaluated, 


and compile the calling function correspondingly. Note that this is only necessary if the compiler 


does not "know" about the function. If the function is defined at compile time, or is handled via a 


macro, or is contained in the same group of files as the functions that call it, the compiler will 
automatically handle calls to that function correctly. 


18.4 GLOBAL VARIABLES VS SHALLOW BINDING. 


Variables that appear on the list globalvars or have the property GLOBALVAR, with value Т, are | 
called global variables. Such variables are always accessed through their top level value when they 
are used freely іп a compiled function. In other words, a reference to the value of this variable is _ 
equivalent to (GETTOPVAL (QUOTE variable)), regardless of whether or not it is bound in the 
current access chain. Similarly, (SETQ variable value) will compile as (SETTOPVAL ene 
variable) value); i.e., it sets the top-level value. 


Note: Interlisp-10 employs a shallow binding scheme as described in Section 12. There is no 
distinction between global variables and other types of variables: all variable references are to the 
variable’s value cell. Thus, the cost of accessing a variable is small and independent of the depth 
of computation, whereas in a deep bound system, it can be expensive to search the stack for the - 
most recent binding of a variable, hence the need for a mechanism like global variables. Note 
however that in a shallow bound system, the cost of rebinding a variable is somewhat higher than. 
in a deep bound system? We employ shallow binding in Interlisp-10 because measurements 


indicated more time would be spent in searching for a variable binding using the deep scheme 
than is lost in rebinding using a shallow scheme. For the purposes of compilation, global variables 


are treated the same as SPECVARS, i.e. their names are always visible on the stack when they are 


rebound. 


All system parameters, unless otherwise specified, are global variables. Thus, rebinding these 
variables in a deep bound system will not affect the behavior of the system: instead, the variables 
must be reset to their new values, and if they are to be restored to their original values, reset again. 
For example, the user might write ..(ЅЕТО globalvar new-value) form (SETQ globalvar old-value). 
Note that in this case, if an error occurred during the evaluation of form, or a control-D was typed, 


Before making this assumption, if the value of compileuserfn is not NIL, the compiler calls (the value of) 
compileuserfn giving it as arguments cdr of the form and the form itself, ie, the compiler does 
(APPLY* COMPILEUSERFN (CDR form) form). If a non-NIL value is returned, it is compiled instead of form. If 
NIL is returned, the compiler compiles the original expression as a call to a lambda-spread that is not yet defined. 
CLISP (Section 23) uses compileuserfn to tell the compiler how to compile iterative statements, IF-THEN-ELSE 
— Statements, and pattern match constructs. Note that compileuserfn is only called when the compiler encounters а list 
саг of which is not the name of a defined function. The user can instruct the compiler about how to compile other 

. data types via compiletypelst, page 18.12. 


The names of functions so treated are added to the list alams (for assumed lambdas). alams is not used by the 
compiler; it is maintained for the user's benefit, ie., so that the user can check to see whether any incorrect 
assumptions were made, 


8 except when the variable is а LOCALVAR. 
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the global variable would not be restored to its original value. The function resetvar (described in - 
Section 5) provides a convenient way of resetting global variables in such a way that their values | 


аге restored even if an error occurred or control-D 15 typed. 


18.5 COMPILER FUNCTIONS 


Note: when a function is compiled from its in core definition, ie. via compile, recompile, or 
brecompile, as opposed to tcompl or bcompl (which uses the definitions on a file), and the function 
has been modified by break, trace, breakin, or advise, it is first restored to its original state, and a 
message printed out, e.g., FOO UNBROKEN. If the function is not defined as an expr, its property 
list is searched for the property EXPR (see savedef, Section 8). If there is a property EXPR, its 
value is used for the compilation. If there is no EXPR and the compilation is being performed by 
recompile or brecompile, the definition of the function is obtained from the file (using loadfns). 
Otherwise, the compiler prints (fn МОТ COMPILEABLE), and 5065 · on to the next function. 


compile[x;flg] x is a list of functions (if atomic, list[x] is used). compile first asks | 


the standard compiler questions, and then compiles each function 
On x, using its in-core definition. Value is x. 


If compiled definitions are being written to а file, the file is closed 
unless flg- T. | | 


compilel[fn;def;-] compiles def, redefining fn if strf=T.? compilel is used бу 


compile, tcompl, and recompile. If dwimifycompflg is T, or def 
contains a CLISP declaration, def is dwimified before compiling. 


See Section 23. 


tcomp [files] | tcompl is used to "compile files", ie. given а symbolic load Ме 
| (е.р., опе created by makefile), it produces a “compiled file" that 

contains the same S-expressions as the original symbolic file, except 

that (1) a special FILECREATED expression appears at the front of 

the file which contains information used by the file package, and 

which causes the message COMPILED 0М19 followed by the date, to 

be printed when the file is loaded; (2) every defineq in the 

symbolic file is replaced by the corresponding compiled definitions 

in the compiled Ве: and (3) expressions of the form 

(DECLARE: -- DONTCOPY --) that appear in the symbolic file 


are not copied to the compiled file. This "compiled" file can ђе 


loaded into any Interlisp system with load. 


9 strf is one of the variables set Бу сотрѕеї, described earlier. 

10 The actual string printed is the value of compileheader, initially "COMPILED ON". The user can reset 
сотрпећсадег, for example to distinguish between files compiled by different systems. 

11 


The compiled definitions appear at the front of the compiled file, i.e., before the other expressions in the symbolic 
file. regardless of where they appear in the symbolic file. Тһе only exceptions are expressions that follow a FIRST 
tag inside of a DECLARE. Scc discussion of DECLARE: below. 
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files is a list of symbolic files to be compiled (if atomic, list[files] is 
used). tcompl asks the standard compiler questions, except for 
OUTPUT FILE: Instead, the output from the compilation of each 
symbolic file is written on a file of the same name suffixed with 
СОМ, 12 eg, icompl[( SYM1 SYM2)] produces two files, SYM1. СОМ 
and SYM2 . СОМ.З 


tcompl processes the files one at a time, reading in the entire file. 

For each FILECREATED expression, the list of functions that were 

marked as changed by the file package (see Section 14) is noted, 
| | and Ше FILECREATED expression is written onto the output Ме. 
i If the rootname of file has property FILETYPE with value CLISP, 
7 or value a list containing CLISP, (сотр! rebinds dwimifycompflg to 

T while compiling the functions on file. For each DEFINEQ 

| expression, tcompl adds апу NLAMBDA's in Ше DEFINEQ to щата 

or laml,> and adds LAMBDA's to the list 125,16 so that calls to 
these functions will be compiled correctly. Expressions beginning 
with DECLARE: .are processed specially as described below. All 
other expressions are collected to be subsequently written onto the - 

output file. After processing the file in this fashion, tcompl 
compiles each function,!’ and writes the compiled definition onto 
the output file. tcompl then writes onto the output file the other 
expressions found in the symbolic file. 


The value of tcompl is a list of the names of the output files. АП 
files are properly terminated and closed. If the compilation of any 
file is aborted via an error or control-D, all files are properly closed, 
and the (partially complete) compiled file is deleted. 


DECLARE: 


For the purposes of compilation, DECLARE: (see Section 14) has two principal applications: (1) to 
Specify forms that are to be evaluated at compile time, presumably to affect the compilation, e.g., 


The actual suffix used is the value of the variable compile.ext, which is initially COM. The user can reset compileext | 


or rename the compiled file after it has been written, without adversely affecting any of the system packages. 


The file name is constructed from the name field only, e.g., tcomp![<BOBROW> FOO. TEM; 3] produces F00.COM on 


the connected directory. The version number will be the standard default. 


for use by recompile and brecompile which use the same low level functions as tcompl and bcompl. 


described earlier, page 18.3. 


nlama, nlaml, and lams are rebound to their top level values (using resetvar) by tcompl, recompile, bcompl, 
brecompile, compile, and blockcompile, so that any additions to these lists while inside of these functions will not 
propagate outside. | | 


except for those functions which appear on the list dontcompilefns, initially NIL. For example, this option might be 


used for functions that compile open, since their definitions would be superfluous when opcrating with the compiled 
Ше. Note that dontcompilefns can be set ма block declarations page 18.20, 
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to set up macros; and/or (2) to indicate which expressions appearing in the symbolic file are not to 


be copied to the output file. (Normally, expressions are по! evaluated and are copied.) Each — 


=- expression in cdr of a DECLARE: form is cither evaluated/not-evaluated and copied/not-copied 
depending on the settings of two internal state variables, initially set for copy and not-evaluate. 


These state variables can be reset for the remainder of the expressions in the DECLARE: by means 
of the tags DOEVALGCOMPILE (ог EVALGCOMPILE), DONTEVAL@COMPILE, DOCOPY (or COPY), 


and DONTCOPY, eg. (DECLARE: DOEVAL@COMPILE DONTCOPY (PROP MACRO --)) could 


be used to set up macros at compile time. The tags EVALGCOMPILEWHEN and COPYWHEN can be 
. used to provide conditional setting of the internal state variables. The expression following the tag 
is cvaluated and determines the setting, eg. ... EVALGCOMPILEWHEN (EQ (SYSTEMTYPE) 
'TOPS20) ... For expressions that are to be copied to the compiled file, the tag FIRST can be 


used to specify that the subsequent expressions in the DECLARE: are to appear at the front of the | 


compiled file, before anything else except the FILECREATED expressions. The tag NOTFIRST 


reverses the effect of FIRST. For example, (DECLARE: COPY FIRST (P (PRINT mess] Т)) | 
NOTFIRST (P (PRINT mess2 T))) will cause (PRINT messl T) to appear first in the шш 


file, followed by any functions, then (PRINT mess2 T). 


Note that the аса loadcomp (Section 14) provides a convenient way of obtaining information 


necessary for compiling one file that is contained in DECLARE: expressions that reside оп another . 


file or files. 


RECOM PILE 


The purpose of ботен is to allow the user to update a compiled file without пе еуегу 
function іп the Ме. Recompile does this by using the results of a previous compilation. It 
produces a compiled file similar to one that would have been produced by tcompl, but at a 


considerable savings in time by compiling selected functions and copying from an earlier tcompl ог - 


recompile file the compiled definitions for the remainder of the functions in the file. 


recompile[pfile;cfile; fns] pfile is the name of the pretty file to be compiled, cfile is the name 
| of the compiled file containing compiled definitions that may be 
copied. fns indicates which functions in pfile are to be recompiled, 
e.g., have been changed or defined for the first time since cfile was 
made. Note that pfile, not fns, drives recompile. 


recompile asks the standard compiler questions, except for OUTPUT 


FILE:. As with tcompl the output automatically goes to 
р с. СОМ. 18 19 recompile ргосе55 pfile the same as does tcompl 
except that DEFINEQ expressions are not actually read into core. 
Instead, recompile uses the filemap (see Section 14)? to obtain a 
list of the functions contained in pfile, and simply skips over the 


18 or pfile.ext, where ext is the value of compile.ext. | 

19 р general, all constructions of the form pfile.COM, pfileCOMS, pfileBLOCKS, etc., are performed using the name field 
only. For example, if ре = <ВОВКОМ> 200. TEM; 3, pfile.COM means РОО. СОМ, pfileCOMS means FOOCOMS, etc. 

20 


A map is built if the symbolic file does not already contain one, с.р., it was written in an earlier system, or with 
buildmapflg=NIL. 
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ПЕҒІМЕ0 5.21 


After this initial scan of pfile, recompile then processes the 
functions defined in the file. -For each function in pfile, recompile 
determines whether or not the function is to be (re)compiled. A 
function is to be recompiled” if (1) fns is a list and the function is 
a member of that list; or (2) fns=T or EXPRS and the function is 
an expr; or (3) fns- CHANGES and the function is marked as 
having been changed in the FILECREATED expression; or (4) 
fns=ALL.”? If a function is not to be recompiled, recompile obtains - 
its compiled definition from с е, and copies it (and all generated - 
subfunctions) to the output Ше, pfile.COM." Finally, after 
processing all functions, recompile writes out all other expressions 

that were collected in the prescan of 1 pfile. | 


ТЕ cfile=NIL, ре. СОМ is used for copying from.” If both fns 
and cfile are NIL, ins is set to the value of recompiledefault, t, which 
is initially EXPRS2 


The value of recompile is the new РЕНИ file, pfile. COM. If 
recompile is aborted due to an error or control-D, the new (partially 
complete) compiled file will be closed and deleted. 


US is designed to allow the user to conveniently and efficiently update a compiled file, even 
when the corresponding symbolic file has not been (completely) loaded. For example, the user can 
perform a loadfrom Aall m 14) to "notice" a symbolic file,“’ and then. дру edit the functions 
he wanted to to change,” call makefile,”? and then Pm tecomplleiphleg 


. 28 


21 те filemap enables recompile to skip over thé DEFINEQ's in the file by simply resetting the file pointer, so that in 
most cases the scan of the symbolic file is very fast (the only processing required is the reading of the non- 
DEF INEQ' 5 and the processing of the DECLARE: expressions as described earlier). 
22 Functions that are members of dontcompilefns are simply ignored. 
23 In this latter case, cfile is superfluous, and in fact does not have to exist. This option is useful, for example, to 
E compile a symbolic file that has never been compiled before, but which has already been loaded (since using tcom mpl : 
| would require reading the file in a second time). 
24 | If the Rincon dés not appear on cfile, recompile simply recompiles it. 
25 In other words, if сте, the file used for obtaining compiled definitions to be copied, is NIL, pfile.COM is used, іе, 
same name as output file but a different version number (one less) than the output file. 
26 . This 15 the most common usage. Typically, the functions the user has changed will have been unsavedefed by the 
| editor, and therefore will be exprs. Thus the user can perform his edits, dump the Ше, and then simply 
recompile[file] to update the compiled file. 
27 The loadfrom would be unnecessary if the compiled file had been previously loaded, since this would also result in - 
- the file having been ‘noticed’. __ | 
As described in Section 9, the editor would automatically load those functions not already loaded. 


29 .. As described in Section 14, makcfile would copy the unchanged functions from the symbolic file. 
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18.6 OPEN FUNCTIONS 


When a function is called from a compiled function, a system routine is invoked that sets up the - 


parameter and control push lists as necessary for variable bindings and return information. As a 


result, function calls can take up to 350 microseconds per call. If the amount of time spent inside | 


the function is small, this function calling time will be a significant percentage of the total time 


required to use the function. Therefore, many "small" functions, e.g., саг, cdr, eq, not, cons are | 


always compiled ' kd ie. they do not result in a function call. Other larger functions such as 
prog, selectg, тарс, еіс. are compiled open because they are frequently used. It is useful to know 


exactly which pre are compiled open in order to determine where a program is spending its | 


time.. Therefore below is а list of those functions which when compiled do not result in function | 


calls. Note that the next section tells BON the user can make other functions compile open via 
MACRO definitions?! 


The following functions compile open? in Interlisp-10: 


AC, А001, AND, APPLY*, АВС,”  ARRAYP, ASSEMBLE, АТОМ,  BLKAPPLY, 
BLKAPPLY*, BOUNDP, CAR, CDR, CAAR, ... CDDDAR, CDDDDR, CLOSER, COND, 


CONS, CONSTANT, COROUTINE, DOCOLLECT, ENDCOLLECT, EQ, EQMEMB, ERSETQ, 


EVALV,9^ EVERY, ЕМО, FASSOC, FCHARACTER, FDIFFERENCE, FGETD, FGREATERP, 
FIX, FIXP, FLAST, FLENGTH, FLOAT, FLOATP, FMEMB, FMINUS, FNTH, FPLUS, 
FQUOTIENT,  FRPLACA,  FRPLACD,  FRPLNODE,  FRPLNODE2,  FRPTQ,  FTIMES, 
FUNCTION, GENERATOR, СЕО, 35 GETATOMVAL, GETFILEPTR, GETHASH, GETPROPLIST, 
GO,  IDIFFERENCE,  IEQP,  IGEQ,  IGREATERP, ILEQ, ILESSP, IMINUS, 
INTERRUPTABLE, IPLUS, IQUOTIENT, IREMAINDER, ІТІМЕ5, JSYS,?6 KWOTE, 
LEQ,7 LISPXWATCH, LIST, LISTP, LITATOM, LLSH, LOC, LOGAND, LOGOR, 
LOGXOR, LRSH, LSH, MAP, MAPC, MAPCAR, MAPCON, MAPCONC, MAPLIST, MINUSP, 


MKLIST, NCONC1, NEQ, NLISTP, NLSETQ, NOT, NOTEVERY, NOTANY, NTYP, NULL, 


NUMBERP, OPENR, OR, POSSIBILITIES, PROG, PROG1, PROGN, RESETFORM, 
. RESETLST, RESETSAVE, RESETVAR, RESETVARS, RETURN, RPTQ, RSH, SELECTQ, 
SET, SETARG, SETATOMVAL, SETN, SETPROPLIST, SETQ, SETQQ, SMALLP, SOME, 


30 Since prettydef automatically outputs a suitable DECLARE: expression to indicate which functions in the file (if any) 
are defined as NLAMBDA's, calls to these functions will be handled correctly, even though the NLAMBDA functions 
themselves may never be loaded, or even looked at, by recompile. | 

3 The user can also affect the compiled code via compileuserfn, described in footnote on page 18.4, and compiletypel st, 
described on page 18.12. | 

32 Some of these compile in-line via macro expansions and some compile so as to use а PUSHJ to jump into system 
code. The important point from the user's standpoint is that all of them do not require a function call. 

33 when the arg variable is bound locally. 

3 when given only one argument. 

35 i.e., compiles open as a call to lessp. However, there is still this function call associated with the geq expression. 

36 When Ше jsys number is itself a small integer, and resultac is either a small number or NIL, e.g. (JSYS 510) but 
not (JSYS N). 

37 


See footnote to GEQ above. 
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STACKP, STRINGP, 5081, SUBSET, SYNTAXP,*® SYSTEMTYPE, TRYNEXT, ТҮРЕМАМЕР, 
ТҮРЕР, UNDONLSETQ, VAG, ZEROP. 


18.7 COMPILER MACROS 


The Interlisp compiler includes a macro capability by which the user can affect the compiled code. 
Macros are defined by placing the macro definition on the property list of the corresponding 
function under the property MAC КО. 39 When the compiler begins compiling a form, it retrieves a 
macro definition for car of the form, if any, and uses it to direct the compilation.4 The three | 


different types of macro definitions are given below. 


(1) Open macros - (LAMBDA ...) ог (NLAMBDA ...) - 


A function can be made to compile open by giving it a macro definition of the form (LAMBDA . » 
or (NLAMBDA ...), e.g., 


(LAMBDA (X) (COND ((GREATERP X 0) X) (T (MINUS X)))) for abs. The effect is as if 
the macro definition were written in place of the function wherever it appears in a function being — 
compiled, i.e., it compiles as an open LAMBDA or NLAMBDA expression. This saves the time | 


necessary to call the function at the price of more compiled code generated. 


(2) Computed macros - (atom expression) 


A macro definition beginning with an atom other than LAMBDA, NLAMBDA, or NIL, allows 
computation of the Interlisp expression that is to be compiled in place of the form. The atom 
which starts the macro definition is bound to cdr of the form being compiled. The expression 
1 the atom is then evaluated, and the result of this evaluation is compiled in place of the 
form. For example, list could be compiled this way by giving it the macro definition: 


38 when class is quoted, e.g. (SYNTAXP X (QUOTE BREAK)). 


39 An expression of the form (DECLARE (DEFLIST ... (QUOTE MACRO))) can be used wifhin a function to 
define a MACRO. DECLARE is defined the same as QUOTE and thus can be placed so as to have no effect on the 
running of the function. 

40 те compiler has built into it how to compile certain basic functions such as car, prog, etc., so that these will not be 

. . affected by macro definitions. These functions are listed above. However, some of them are themselves implemented 

via macros, so that the user could change the way they compile. | | 


4l qn Interlisp-10, if the result of the evaluation is the atom INSTRUCTIONS, no code will be generated by the 

compiler. It is then assumed the evaluation was done for effect and the necessary code, if any, has been added. This 

. is a way of giving direct instructions to the compiler if you understand it. If the result of the cvaluation is the atom 

IGNOREMACRO, the macro is ignored and the compilation of the expression proceeds as if there were no MACRO 

property. The difference between IGNOREMACRO and INSTRUCTIONS is that if the atom in question is normally 

treated specially by the compiler, e.g. car, cdr, cond, and, etc., and also has a macro, for those cases which the macro 
expansion returns IGNOREMACRO, the atom will still be treated specially. 
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D (LIST (QUOTE CONS) 
(CAR X) 
(AND (CDR X) 
(CONS (QUOTE LIST) 
(CDR X] 


This would cause (LIST X Y Z) to ERT as (CONS X (CONS Y (CONS Z NIL))). Note | 


the recursion in the macro expansion.” Ersetg, nlsetg, тар, тарс, тарсаг, mapconc, and some, 
are compiled via macro definitions of this type. | | | | 


(3) Substitution macro - (NIL expression) or (list expression) 


Each argument in the form being compiled is substituted for the corresponding atom in car of the 
macro definition, and Ше result of the substitution is compiled instead о; the. form, i i.e., the 
compiler performs 


(SUBPAIR (CAR macrodef) (CDR form) (CADR macrodef)), and compiles the result. For 
example, the macro definition of addl is ((X) (IPLUS X 1)). Thus, (ADD1 (CAR Y)) is 
compiled as (IPLUS (CAR Y) 1). The functions ада], subl, neq, пісір, zerop, flength, fmemb, 
fassoc, flast, and fnth are all compiled open using substitution macros. Note that abs could be 
compiled open as shown earlier or via a substitution macro. А substitution macro, however, would 
cause (ABS (FOO X)) to compile as 

(COND ((GREATERP (FOO X) 0) (FOO X)) (T (MINUS (Foo )9)) and consequently 
(FOO X) would be evaluated three times. 


The following function is quite useful for debugging macro definitions: 


expandmacro[form;quietflg ^ takes a form whose car has a macro definition and expands the | 
| form as it would be compiled. The result is prettyprinted on the 


terminal, unless ашеша = Т, in which case the result is simply 
returned. 


CONSTANT 


The function constant enables the user to define certain expressions as descriptions of their 


"constant" values. For example, if a user program nceded a scratch list of length 30, the user 
could specify (CONSTANT (to 30 collect NIL)) instead of (QUOTE (NIL NIL ...)). The 
former is morc concise and displays the important parameter much more directly than the latter. 
constant can also be used to denote values that cannot be quoted directly: 
(CONSTANT (PACK NIL)), (CONSTANT (ARRAY 10)). It is also uscful to parameterize 


quantities that are constant at run time but may differ at compile time, e.g. (CONSTANT 


bitsperword) in a program is exactly equivalent to 36, if the variable bitsperword is bound to 36 
when the constant expression is evaluated at compile time. 


. When interpreted, the expression occuring as the argument to constant is evaluted each time it is 


42 


list is actually compiled more efficiently. 
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encountered, If the constant form is compiled, however, the expression will be evaluated only. 
once: | 


If the value of the expression has a readable print-name, then it will be evaluated at | 

compile-time, and the value will be saved as a literal in the compiled function's 

definition, as if (QUOTE уаш орноп) had appeared instead of (CONSTANT 
E expression). 


If the value does not have a readable printname A g. the PACK and ARRAY NS | 
then the expression itself will be saved with the function, and it will be evaluated | 
when the function is first executed. The value will then be stored. in the function’ $ 
literals, and will be retrieved оп future references. 


‘Whereas the function constant attempts to evaluate the expression as soon as possible (compile- | 
time, load-time, or first-run-time), the function deferredconstant will always defer the evaluation 


until first running. This is useful when the storage for the constant is excessive so that it shouldn't. 
be allocated until (unless) the function is actually invoked. | | 


сом PILETY PELST 


Most of the compiler's mechanism deals with how to handle forms (lists) and variables (literal 
atoms). The user can affect the compiler's behaviour with respect to lists and literal atoms in a 
number of ways, e.g. compiler macros, declarations, compileuserfn, etc. compiletypelst allows the 


user to tell the compiler what to do when it encounters a data type other than a list or an atom. It 
15 the facility in the compiler that corresponds to defeval (Section 8) for the eS | | 


compiletypelst is a list of elements of the form (type-name facon. Whenever the compiler 
encounters a datum that is not a list and not an atom (or a number) in a context where the datum 


is being evaluated, the type-name of the datum is looked up on compiletypelst, ie. 


assoc[typename[datum];compiletypelst] is performed. If an entry appears car of which is equal to 
the typename, cdr of that entry is applied to the datum. If the value returned by this application is 


-not ед to the datum, then that value is compiled instead. If the value is eq to the datum, or if 


there is no entry on compiletypelst for this typename, the ааа р compiles the datum аѕ 


(QUOTE datum). 


МАСВОТВАМ 


MACROTRAN is а package that enables the user to run programs interpretively which contain calls 
to functions which are only defined in terms of a compiler macro. MACROTRAN is implemented via 


"ап entry on dwimuserforms (Section 17).43 When the interpreter encounters a form car of which is 


an undefined function, macrotran is called. 1f car of the form has a MACRO property, y, the macro is 
expanded, and the result of this expansion is evaluated in place of the original form.“ If car of the 


43 ала thus will not work if DWIM is not enabled. 


44 clisptran (Section 23) is used to save the result of this expansion so that the expansion only has to be done once. On 
subsequent occasions, the translation (expansion) is retrieved from clisparray the same as for other clisp РСК 


тасто ап never even has to be invoked. 
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form is ASSEMBLE (see page 18. 24), or the macro contains an ASSEMBLE directive, instead of 


the macro being expanded, a dummy function is created with the form as its definition, and the- 


dummy function is then compiled. 46 47 A form consisting of a call to this dummy function with no 
arguments is then evaluated in place of the original form. 


18.8 FUNCTION AND FUNCTIONAL ARGUMENTS 


Expressions that begin with FUNCTION are compiled as separate functions f? named by attaching а. 


gensym to the end of the name of the function іп which they appear, e.g., ҒО0А0003. This 
gensym function will be called at run time. Thus if FOO is defined as | 

(LAMBDA (X) ... (Ғ001 X (FUNCTION ...)) ...) and compiled, then when FOO is run, 
FOO1 will be called with two arguments, X, А and ҒООА000п, and Шеп F001 will call 
FOOA000n each time it must use its functional argument. 


Note that a considerable savings in time could be achieved by making FOO1 compile open via a 
computed macro, e.g. 

(7 (LIST (SUBST (CADADR 7) (QUOTE FN) def) (CAR 7))) 
where def is the definition of Ғ001 as a function of just its first argument and FN is the name 
used for its functional argument in its definition. The expression compiled contains what was 


previously the functional argument to F001, as an open LAMBDA expression. Thus you save not 


only the function call to Ғ001, but also each of the function calls to its functional argument. For 
example, if ЕОО1 operates on a list of length ten, eleven function calls will be saved. Of course, 
this savings in time costs space, and the user must decide which is more important. 


18.9 BLOCK COMPILING 


Block compiling provides a way of compiling several functions into a single block. Function calls 
between the component functions of the block are very fast. Thus, compiling a block consisting of 
just a single recursive function may be yield great savings if the function calls itself many times, 
e.g., equal, copy, and count are block compiled in Interlisp-10. 


The output of a block compilation is a single, usually large, function. Calls from within the block 
to functions outside of the block look like regular function calls, except that they are usually linked 
(described below). A block can be entered via several different functions, called entries. These 


45 or contains calls to functions which affect the compiler directly, e.g. cexp, storein, etc. 


46 There are some situations for which this procedure is not amenable, e.g. a go inside the form which is being 
compiled will cause the compiler to give an UNDEFINED TAG error message because it is not compiling the entire 
function, just a part of it. 


47 Note that macrotran will work on macros that do not contain ASSEMBLE directives even if the compiler is not 
loaded. ASSEMBLE directives, however, require the compiler. 

48 and clisptran used to save the translation as described above. 

49 except when they are compiled open, as is the case with most of the mapping functions, 

50 


or an appropriate funarg expression, sce Section 11. 
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must be specified when the block is сотрйса,51 For example, the error block has three entries, 
errorx, interrupt, and faultl. Similarly, the compiler block has nine entries. 


RETFNS 
Another savings in block compilation arises from omitting most of the information on the stack 
about internal calls between functions in the block. However, if a function's name must be visible 


on the stack, e.g., if the function is to be returned from retfrom, retto, reteval, etc., it must be 
included on the list retfns. | 


BLKAPPLYFNS 


Normally, a call to apply from inside a block would be the same as a call to any other function | 


. Outside of the block. If the first argument to apply turned out to be one of the entries to the 


block, the block would have to be геепѓегед. blkapplyfns enables a program to compute the name 
of a function in the block to be called next, without the overhead of leaving the block and 
reentering it. This is done by including on the list blkapplyfns those functions which will be called 
in this fashion, and by using blkapply in place of apply, and blkapply* in place of apply*. For 
example, the calls to the functions handling RI, RO, LI, LO, BI, and BO in the editor аге - 
handled this way. If blkapply or blkapply* is given a function not on blkapplyfns, the effect is the 
same as a call to apply or apply* and no error is generated. Note however, that blkapplyfns must 
be set at compile time, not run time, and furthermore, that all functions on pikapplyins п must be in 
the block, Or an error is Везе (at compile time), МОТ ОМ BLKFNS. 


'BLKLIBRARY 


Compiling a function open via a macro provides a way of eliminating a function call. For block 
compiling, the same effect can be achieved by including the function in the block. А further 
advantage is that the code for this function will appear only once in the block, whereas when a 
function is compiled open, its code appears at each place where it is called. 


The block library feature provides a convenient way of including functions in a block. It is just a 
convenience since the user can always achieve the same effect by specifying the function(s) in 
. question as one of the block functions, provided it has an expr definition at compile time. The 
block library feature simply eliminates the burden of supplying this definition. 


To use the block library feature, place the names of the functions of interest on the list blklibrary, 
and their EXPR definition on the property list of the function under the property 
BLKLIBRARYDEF. When the block compiler compiles a form, it first checks to see if the function 
being called is one of the block functions. If not, and the function is on blklibrary, its definition is 
obtained from the property value of BLKLIBRARYDEF, and it is automatically included as part of 
the block. The functions assoc, equal, getprop, last, length, lispxwatch, тето, member, nconcl, 
пећ, nth, /rpInode, and (апр already have BLKLIBRARYDEF properties. 


51 Actually the block is entered the same as every other function, 1.е., at the top. However, the entry functions call the 
. main block with their name as one of its arguments, and the block dispatches on Ше name, and jumps to the portion 
of the block corresponding to that entry point. The effect is thus the same as though there were several different 


entry points. 
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18.10 LINKED FUNCTION CALLS 


Conventional (non-linked) function calls from a compiled function go through the function 
definition cell, i.e., the definition of the called function is obtained from its function definition cell - 


at call time. Thus, when the user breaks, advises, or otherwise modifies the definition of the 
function ЕОО, every function that subsequently calls it instead calls the modified function. For 
calls from the system functions, this is clearly not a feature. For example, the user may wish to 
break on basic functions such as print, eval, rplaca, etc., which are used by the break package. In 
other words, we would like to guarantee that the system packages will survive through user 
modification (or destruction) of basic functions (unless the user specifically requests that the system 
packages also be modified). This protection is achieved by linked function calls. - | 


For linked function calls, the definition of the called function is obtained at /ink time, i.e., when 
the calling function is defined, and stored in the literal table of the calling function. At call time, 
this definition is retrieved from where it was stored in the literal table, not from the function 
definition cell of the called function as it is for non-linked calls. These two пори types of calls 
are illustrated in Figure 18-1. 


Note that while function calls from block Тл functions are usually linked (i.e. the default for 
blocks is to link)??, and those from standardly compiled functions are usually non-linked, linking 
function calls and blockcompiling are independent features of the Interlisp compiler, i.e., linked 
function calls are possible, and frequently employed, from standardly compiled functions. 


52 Іп Interlisp-10, linked function calls are actually a little slower and take more space than non-linked calls, so that the 


uscr might want to include (NOLINKFNS . T) in block declarations to override the default. 
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Note that normal function calls require only the called function's name іп the literals of the- 
compiled code, whereas a linked function call uses two literals and hence produces slightly larger 
compiled functions. 


The compiler's decision as to whether to link a particular function call is determined by (ће | 
. variables linkfns and nolinkfns as follows: 


(1 Ifthe function appears on nolinkfns, the call is not linked; | 
(2) If block compiling and the function is one of the block functions, the call is internal as 
. described earlier; 
(3) If the function appears on linkfns, the call is linked; | 
(4) If nolinkfns=T, Ше call is not linked; 
(5) If block compiling, the call is linked; 
(6)  Iflinkfns- T, the call is linked; 
(7 Otherwise the call is not linked. 


| Note that (1) takes precedence over (2), i.e., if a function appears on nolinkfns, the call to it is лог 
linked, even if it is one of the functions in the block, 1.е., the call will go outside of the block. 


Nolinkfns is initialized to various system functions such as errorset, breakl, etc. Linkfns is 
initialized to NIL. Thus if the user does not specify otherwise, all calls from a block compiled 
function (except for those to functions on nolinkfns) will be linked; all calls from standardly 
compiled functions will not be linked. However, when compiling system functions such as help, 
error, arglist, fntyp, breakl, et al, linkfns is set to T so that even though these functions are not 
block compiled, all of their calls will be linked. 


If a function is not defined at link time, 1.е., "m an attempt is made to link to it, it is linked 
instead to the function nolinkdef. When the function is later defined, the link can be completed 
by relinking the calling function using relink described below. Otherwise, if a function is run 
which attempts a linked call that was not completed, nolinkdef is called. If the function is now | 
defined, i.e., it was defined at some point after the attempt was made to link to it, nolinkdef will 
quietly perform the link and continue the call. Otherwise, it will call faultapply and proceed as. 
described in Section 16. 


calls, break on fnl-IN-fn2 and advise fnl-IN-fn2 all work correctly for linked function calls, e.g., 
break[( FOO IN FIE)] where FOO is called бот ЕТЕ via a linked function call. Note that 
control-H will not interrupt at linked function calls. 


RELINKING 


The function relink is available for relinking a compiled function, i.e., updating all of its linked - 
calls so that they use the definition extant at the timc of the relink operation. 


relink[fn] fn is cither WORLD, thc name of a function, a list of functions, or an 
atom whose value is a list of functions. relink performs Ше 
corresponding rclinking operations.  relink[WORLD] is possible 
because the compiled code reader maintains on linkedfns a list of | 
all user functions containing any linked calls. syslinkcdfns is a list 
of all system functions that have any linked calls. relink[WORLD] 
performs both rclink[linkedfns] and relink[syslinkedfns]. 


The value of relink is fn. 
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It is important to stress that linking takes place when a function is defined. Thus, if FOO calls ЕТЕ 


via a linked call, and a bug is found in ЕТЕ, changing ЕТЕ is not sufficient; FOO must be relinked. | 
Similarly, if 2001, Ғ002, and ЕООЗ are defined (in that order) in a file, and each call the others 
via linked calls, when a new version of the file is loaded, 2001 will be linked to the old F 002 and 
2003, since those definitions will be extant at the time it is read and defined. Similarly, F002 will 


link to the new F001 and old F003. Only F003 will link to the new ЕОО1 and F002. The user 


would have to perform ыш OOFNS] ад. the load. 


18. 14 LOCALVARS AND SPECVARS 


In normal compiled and interpreted code, all variable bindings are „пеене by lower level 


functions because the variable’s name is associated with its value. We call such variables special | 


variables, or specvars. As mentioned earlier, the block compiler normally does not associate names | 
with variable values. Such unnamed variables are not accessible from outside the function which - 
binds them and are therefore local to that function. We call such unnamed variables local А 
variables, or localvars.. 


The time economies of local variables can be achieved without block compiling by use of 
declarations. Using local variables will increase the speed of compiled code; the price is the work 
of writing the necessary specvar declarations for those variables which need to be accessed. from 
outside the block. | | Ж | 


localvars and specvars are variables that affect compilation. During regular compilation, spec ars is 
normally T, and localvars is NIL or a list. This configuration causes all variables bound in the - 
functions being compiled to be treated as special except those that appear on localvars. During 
block compilation, localvars is normally T and specvars is NIL or a list. All variables are then 
treated as local except those that appear on specvars. | т 


Derna to set localvars and s specvars rs to other values, and therefore affect how variables are 


treated, may be used at several levels in the compilation process with varying scope. (1) They may 
be included in the COMS of a file scope of the declaration is then the entire file, e.g. 


(LOCALVARS . T), (SPECVARS X Ү).53 


(2) The declarations may be included in block declarations; the scope is then the block, eg., 


(BLOCKS ((FOOBLOCK FOO ЕТЕ (SPECVARS . T) (LOCALVARS Х))).. 


(3) The declarations may also appear in individual functions, or in prog's or lambda's within a 
function. In this case the scope of the declaration is the function or Ше prog or r lambda in which. 
it appears. localvars and specvars declarations must appear immediately after the variable list in 
the function, prog, or lambda, but intervening comments are permitted. For example: 


(DEFINEQ (( FOO 
| (LAMBDA (Х Y) 
(DECLARE (LOCALVARS Y)) 
(PROG (X Y Z) 
(DECLARE (LOCALVARS X)) 


33 LOCALVARS and SPECVARS are also the names of file package commands, which is why this works. They output 


the indicated expression, first embedding it inside of a DECLARE: DOEVAL@COMPILE DONTCOPY, 
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] 


If the above function is compiled (non-block), the outer X will be special ше X bound in the prog | 
will be local, and both bindings of Y will be local. 


Declarations foi localvars and specvars can be used in two ways: either to cause variables to. be 
treated the same whether the function(s) are block compiled or compiled normally, or to affect one 
compilation mode while not affecting the default in the other mode. For example: Е 
(LAMBDA (Х Y) | 
(DECLARE (SPECVARS . T)) 
(PROG (7) ... 1 


_ will cause X, Y, and Z to be specvars for both block and normal compilation while 


(LAMBDA (X Y) 
(DECLARE (SPECVARS X)) 
күт 


will make Х а specvar when block compiling, but when regular compiling the declaration will have 
no effect, because the default value of specvars would be Т, and therefore both Х and Y will be 
specvars by default. | 


Although localvars and specvars declarations have the same form as other components of block 
declarations such as (LINKFNS . T), their operation is somewhat different because the two 
variables are not independent. (SPECVARS . T) will cause specvars to be set to T, and localvars 
to be.set to NIL. (SPECVARS V1 V2 ...) will have no effect if the value of s Specvars is T, but 
if it is a list (or NIL), specvars will be set to the union of its prior value and (V1 V2 ...). The 
operation of localvars is analogous. Thus, to affect both modes of compilation опе of the two 
(localvars or specvars) must be declared T before specifying а list for the other. | | 


18.12 THE BLOCK COMPILER, 


There are three user level functions for blockcompiling, blockcompile, bcompl, and brecompile, 

corresponding to compile, tcompl, and recompile. All of them ultimately call the same low level 
functions in the compiler, i.e., there is no 'blockcompiler' per se. Instead, when blockcompiling, a 
flag is sct to enable special treatment for specvars, rctfns, blkapplyfns, and for determining whether 
or not to link a function call. Note that all of the previous remarks on macros, globalvars, 
compiler messages, сіс., all apply equally for block compiling. Using block declarations described 
below, the user can intermix in a single file functions compiled normally, functions compiled . 
normally with linked calls, and block compiled functions. 


BLOCKCOMPILE 
blockcompilc[blkname;blkfns;entrics; flg] 
blkfns is a list of the functions. comprising the block, blkname is the 
namc of the block, entries a list of entries to the block, e.g., 
-BLOCKCOMPILE(SUBPRBLOCK (SUBPAIR SUBLIS SUBPR) (SUBPAIR SUBLIS)) 


Each of the entries must also Бе on blkfns or an error 15 gencrated, 
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МОТ ON BLKFNS.?4 


If entries is NIL, list[blkname] is used, e.g., 
«BLOCKCOMPILE(COUNT (COUNT COUNT1)) 


If bikfns is NIL, list[blkname] is used, e.g., 
-BLOCKCOMPILE( EQUAL ) | 


blockcompile asks the standard compiler questions and then begins | 
compiling. As with compile, if the compiled code is being written 
. to a file, the file is closed unless Йе = T. The value of blockcompile 
is a list of the entries, or if entries=NIL, the value is blkname. 


The output of a call to blockcompile is one function definition for 
blkname, plus definitions for each of the functions on entries if any. 
These entry functions are very short functions which immediately 
call blkname. | | 


| BLOCK DECLARATIONS. 


. Since block compiling a file frequently involves giving the compiler a lot of information about ће 


nature and structure of the compilation, e.g., block functions, entries, specvars, linking, et al, we 
have implemented a special prettydef command to facilitate this commmunication. The user | 
includes in the fileCOMS a command of the form (BLOCKS block, .. . block» ... block) where each | 


block, is a block declaration. bcompl and brecompile described below are sensitive to these 
declarations and take the appropriate action.” | 


тһе ioa of a block declaration is: 


 (blkname bikfny ... ЫК, (vary . value) ... (хаг. value)) 


Ык... ЫК! are the functions in the block and correspond to blkfns in the call to 


| оссо рс he (var. value) рш: indicate the settings for variables affecting the 


compilation. 


Ав an ЕЕ ЈЕ the value of editblocks is shown below. It consists of three block declarations, БА 


editblock,  editfindblock, and edit4e. 


54 If only опе entry is specified, the block пате can also be опе ог the Ып, ер, 
= BLOCKCOMPILE(FOO (FOO FIE FUM) (Ғ00)). However, if more than one entry is specified, an error will be 


generated, CAN'T BE BOTH AN ENTRY AND THE BLOCK NAME. 


55 Note: Masterscope (Section 20) includes a facility for checking the block declarations of a Ше or files for various 
anomalous conditions, e.g. functions in block declarations which aren't on the file(s), functions in ENTRIES not in 
the block, variables that may not need to be SPECVARS because they are not used freely below the places hey are 
bound, екс. 
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[RPAQQ EDITBLOCKS 
((EDITBLOCKEDITLO EDITL1 UNDOEDITL EDITCOM EDITCOMA EDITCOML 
EDITMAC EDITCOMS EDIT]UNDO UNDOEDITCOM 
UNDOEDITCOM1 EDITSMASH EDITNCONC EDIT1F EDIT2F 
EDITNTH BPNT BPNTO BPNT1 RI RO LI LO BI BO — 
EDITDEFAULT ## EDUP EDIT* EDOR EDRPT EDLOC EDLOCL 
EDIT: EDITMBD EDITXTR EDITELT EDITCONT EDITSW 
С EDITMV EDITTO EDITBELOW EDITRAN TAILP EDITSAVE 
EDITH (ENTRIES EDITLO 44 UNDOEDITL) 
(SPECVARS L COM LCFLG #1 42 #3 LISPXBUFS 
**COMMENT**FLG PRETTYFLG UNDOLST - 
UNDOLST1) — 
(RETFNS EDITLO) 
(GLOBALVARS EDITCOMSA EDITCOMSL EDITOPS 
С HISTORYCOMS EDITRACEFN) 
(BLKAPPLYFNS RI RO LI LO BI BO EDIT: EDITMBD 
EDITMV EDITXTR) | 
(BLKLIBRARY LENGTH NTH LAST) | 
(NOLINKFNS EDITRACEFN)) 
(EDITFINDBLOCK EDIT4E ЕРІТ4Е1 EDITQF EDIT4F EDITFPAT 
EDITFPAT1 EDIT4F1 EDIT4F2 EDIT4F3 EDITSMASH 
EDITFINDP EDITBF EDITBF1 ESUBST. 
(ENTRIES EDITQF EDIT4F EDITFPAT EDITFINOP 
EDITBF ESUBST)) | 
(EDITAEBLOCK EDITAE EDIT4E1 (ENTRIES EDITAE EDIT4E1] | 


. Whenever bcompl or brecompile encounter a block declaration®® they rebind retfns, specvars, 
localfreevars, globalvars, blklibrary, nolinkfns, Пакт, and dontcompilefns to their top level value, 
bind blkapplyfns and entries to NIL, and bind blkname to the first element of the declaration. 
They then scan the rest of the declaration, gathering up all atoms, and setting car of each 
nonatomic element to cdr of the expression if atomic, e.g, (LINKFNS . T), or else to union of 

· cdr of the expressions with the current (rebound) value,?? e.g., 
(GLOBALVARS EDITCOMSA EDITCOMSL). When the declaration is exhausted, the block 
compiler is called and given blkname, the list of block functions, and entries. 


Note that since all compiler variables are rebound for each block declaration, the declaration only 
has to set thosc variables it wants changed. Furthermore, setting a variable in one declaration has 
no effect on the variable's value for another declaration. 


After finishing all blocks, bcompl and brecompile treat any functions in thc file that did not appear 
in a block declaration in the same way as do tcompl and recompile. If the user wishes a function 
compiled separately as well as in a block, or if he wishes to compile some functions (not 
blockcompile), with some compiler variables changed, he can use a special pseudo-block declaration 


56 Тһе BLOCKS command outputs a DECLARE: expression, which is noticed by bcompl and brecompile. 

57 Expressions of the form (var * form) will cause form to be evaluated and the resulting list used as described above, 
e.g., (GLOBALVARS * MYGLOBALVARS ). 

58 


If a function appears in a block declaration, but is not defined in onc of the files, then if it has an in-core definition, + 
this definition is used and a message printed NOT ON FILE, COMPILING IN CORE DEFINITION. Otherwise, + 
the message NOT COMPILEABLE, is printed and the block declaration processed as though the function were noton + 

it, i.e. calls to the function will be compiled as external function calls. | 
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of the form (NIL пу... ‚ба, (var, . value) ... (var, . value)) which means compile б. ~ Вп after 
first setting var) ... vary as described above. F or example, | 
(NIL CGETD FNTYP ARGLIST NARGS МСОМС1 GENSYM (LINKFNS . T)) 

appearing as a "block declaration" will cause the six indicated functions to be compiled. while 
linkfns=T so that all of their calls will be linked (except for those functions on nolinkfns). 


BCOMPL 


bcompl[files;cfile] _ | files is a list of symbolic files. (If atomic, list[files] is used.) bcompl 
differs from tcompl in that it compiles all of the files at once, 
instead of one at a time, in order to permit one block to contain 
functions in several files? 59 Output is to cfile if given, otherwise to а 
file whose. name is сай ез) suffixed with COM, 9 е g., 
bcompl[(EDIT WEDIT)] produces опе file, EDIT . СОМ. 


bcompl asks the standard compiler questions, except for OUTPUT _ 
FILE:, then processes each file exactly the same as does tcompl | 

(see page 18.6).61 62 Bcompl next processes the block declarations as 
described above. Finally, it compiles those functions not mentioned 
in one of the block declarations, and then writes out all other 
expressions. 


The value of bcomp! is the output file (the new compiled file). If 
the compilation is aborted due to an error or control-D, all files are | 
closed and the (partially complete) output file is deleted. | 
Note that it is permissible to tcompl files set up Юг Бсотр!; the 
= block declarations will simply have no effect. Similarly, you can 


bcompl a file that does not contain any block declarations and the 
result will be the same as having icompled it. 


BRECOMPILE 


Brecompile plays the same role for bcompl that recompile plays for tcompl: its purpose is to allow 
| the user to update a compiled file without requiring an entire bcompl. 


59  Thusif you have several files to be bcompled separately, you must make several calls to bcompl. 
-or value of compile.ext, as explained earlier. 


бі р fact, tcompl is defined in terms of bcompl The only difference is that tcompl calls bcompl with an extra 
. argument specifying that all block declarations are to be ignored. 


j 92 If any of the files have property FILETYPE with value CLISP, or a list containing CLISP, then dwimifycompflg is 
rebound to T for all of the files. | | 
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files is a list of symbolic files (if atomic, list[files] is used). cfile is 


the compiled file corresponding to bcompl[files] or a previous - 


brecompile, i.e., it contains compiled definitions that may be copied. 


‘The interpretation of Шз! 15 Ше same as with recompile.? 


brecompile asks the standard compis questions except for OUTPUT 
FILE: As with bcompl, output automatically goes to file.COM, 
where file is the first file in files. 


| brecompile processes. šach file the same as does recompile as 


described on page 18.7, then processes each block declaration. If 
any of the functions in the block are to be recompiled, the entire 
block must be (is) recompiled. Otherwise, the block is copied from 
cfile as with recompile. For pseudo- -block declarations of the form 
(NIL fnl ...), all variable assignments are made, but only those 
functions so indicated by fns are recompiled. | 


After completing the block declarations, brecompile processes all 


_ functions that do not appear in a block declaration, recompiling 


those dictated by fns, and copying. t the кыры definitions of the 
remaining from cfile. 


Finally, бср. а writes onto the output file the "other 


expressions" collected in the initial scan of files. 


The value of brecompile is the output file (the new compiled file). 
If the compilation is aborted due to an error or control-D, all files - 
are closed and the (partially complete) output file is deleted. 


If cfile=NIL, file.COM is used. In addition, if fns and cfile are 
both NIL, fns is set to the value of recompiledefault à initially 
EXPRS.. 


18.13 COMPILER STRUCTURE 


The compiler. has two principal passes. The first compiles its input into a macro assembly language 
called LAP.© Тһе second pass expands the LAP code, producing (numerical) machine language - 
instructions. The output of the second pass is written on a file and/or stored in binary program 


space. 


Input to the compiler is usually a standard. Interlisp S-expression function definition. However, in 


63 


In fact, recompile is defined in terms of brecompile. The only difference is that recompile calls brecompile with an 


extra argument specifying that all block declarations are to be ignored. 


65 


See footnote on page 18.7. 


The exact form of the macro assembly language is extremely implementation dependent, as well as being influenced 


by the architecture and instruction sct for the machine that will run the compiled program. The remainder of 
Section 18 discusses LAP for {һе Interlisp-10. 
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Interlisp-10, machine language coding can be included within a function by the use of one or more 
assemble forms as described below. In other words, assemble allows the user to write portions of a 
function in LAP. Note that assemble is only a compiler directive; it has no independent definition. 
Therefore, functions which use assemble must normally be compiled in order to run. 


18.14 ASSEMBLE 


Note: assemble is sodda for situations where its use is unavoidable. However, its use is 


defi nitely not encouraged. The disadvantages are several. assemble code is unavoidably dependent 
on Ше PDP-10, TENEX, and implementation details of Interlisp-10. Thus, assemble code is not 
transportable to Interlisp on another machine or operating system, and implementation changes to 
Interlisp-10 can (and. frequently do) require changes to existing assemble code. | 


The format of assemble is similar to that of PROG: (ASSEMBLE V 51 So. 2 515 ae Visa 
list of variables to be bound during the first = of the compilation, not during the fanning of the 


object code. The assemble statements E Sp are compiled sequentially, each resulting in one 
en run, 


or more instructions of object code. W e value of the assemble "form" is the contents 
of ACI at the end of the execution of the assemble instructions. М ote that assemble may appear 
суши in an Interlisp-10 function. For example, one may write: 


(IGREATERP. (IQUOTIENT (LOC (ASSEMBLE NIL 
.. (MOVEI 1, -5) 

(JSYS 13))) 

· 1000) а 

4) ШЕ 


‘to test if job runtime exceeds 4 seconds.9? 


ASSEMBLE STATEMENTS | 


ІҒ ап РИТТЯ statement 15 an atom, it is treated as a label identifying the location of the next | 
statement that will be assembled.®8 Such labels defined іп an assemble form are like prog labels in | 
that they may be referenced from the current and lower level nested progs or assembles. 


If an assemble statement is not an atom, car of the statement must be an atom and one of the 


· following: (1) a number; (2) a LAP op-def (.е., has a property value OPD); (3) an assembler macro 


(i.e., has a property value АМАС); ог (4) one of the special assemble instructions given below, e.g., 
C, CQ, etc. Anything else will cause the error message OPCODE? - ASSEMBLE. 


Тһе types of assemble statements are described here in the order of priority used іп the assemble — 


The MACROTRAN package (page 18.12) does permit the user to run programs interpretively which contain assemble - 
. directives. Each assemble directive is compiled as a separate function. There is some loss in efficiency over compiling 
the entire function as a unit, and not all assemble expressions are tractable to this procedure. | 


67 ТЕ example is to illustrate use of assemble, and is not a recommendation to use the above code. The function js n isis 


(Section 21) is the appropriate method. 


A label can be the last thing in an assemble form, in which case it labels the ейн of the first instruction after the 
assemble form. 
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processor; that is, if an atom has both properties OPD and AMAC, the OPD will be used. Similarly а 
special assemble instruction may be redefined via an AMAC. ‘The following descriptions аге of the 
. first pass processing of assemble statements. The second pass DOE is described i in the section 
on LAP, page 18.27. 


(1) numbers 


If car of an assemble statement is a number, the statement is not processed in the first Бине (See 
page 18.27.) | 


(2) ГАР op-defs 


The property ОРО is used for two different types of op-defs: PDP-10 machine instructions, апа 
LAP macros. If the ОРО definition (1.е., the property value) is a number, the op-def 15 a machine 
instruction. When a machine instruction, e.g., HRRZ, appears as car of an assemble statement, the 
statement is not processed during the first pass but is passed to LAP. The forms and processing of 

machine instructions by LAP are described on page 18.28. | 


If the ОРО definition is not а number, then the op-def is а LAP macro. When а LAP macro is 
encountered in an assemble statement, its arguments are evaluated and processing of the statement 
with evaluated arguments is left for the second pass and LAP. For example, LDV is a LAP macro, 
and (LDV (QUOTE X) SP) in assemble code results in У Х г) іп the LAP code, where Nis- 
the value of SP. 


The form and processing of LAP macros are described on page 18.29. 


(3) assemble macros 


If car of an assemble statement has a property AMAC, the statement is an assemble macro call. 
There are two types of assemble macros: lambda and substitution. If car of the macro definition is 
the atom LAMBDA, the definition will be applied to the arguments of the call and the resulting list | 
of statements will be assembled. For example, repeat could be а LAMBDA macro with two 
arguments, n and m, which expands into n occurrences of m, e.g., (REPEAT 3 (CAR1)) expands 
to ((CAR1) (CAR1) (CAR1)). The definition (i.e., value of property AMAC) for repeat is: 


(LAMBDA (N M) 
(PROG (YY) 
A (COND 
((ILESSP N 1) 
(RETURN (CAR YY))) 
(T (SETQ YY (TCONC ҮҮ M)) 
(SETQ N (5081 N)) 
(60 А))))) 


If саг of the macro definition is not the atom LAMBDA, it must be а list of dummy symbols. The 
arguments of the macro call will be substituted for corresponding appearances of the dummy 
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symbols in cdr of the definition, and the resulting list of statements will be assembled. 69 Б or 
example, abs ; could be a substitution macro which takes one argument, a number, and права into 
· instructions to place the absolute value of the number in ACI. | 


The definition of ABS is: 


((X) 
(CQ (VAG X)) 
(CAIGE 1, 0)) 
(МОМ, 1 , 1)) 


(4) special assemble statements 


(CQ 5152...) CQ (compile quote) takes any number of arguments which are 
. assumed to be regular S-expressions and are compiled in the 
normal way. Eg. | 
(CQ (COND ((NULL Y) (SETQ Y 1))) 
(SETQ X (IPLUS Y Z))) 


Note: to avoid confusion and minimize dependence on the current implementation, it is best to 
have as much of a function as possible compiled in the normal way, e.g., to load the value of x to 
AC1, (CQ X) is preferred to (LDV (QUOTE X) SP). 


(C sy 55 ...) C (compile) takes any number of ТОТ which аге first 
| evaluated, then compiled in the usual way. Both С and СО permit 
the inclusion of regular compilation within an assemble form. 


(E еј ер...) Е (evaluate) takes any number of arguments which are evaluated іп 
| mE sequence. For example, (РУТЕР) calls a function which 
increments the compiler variable SP. АЕ | 


(ФЕТО var) . . Compiles code to set the variable var to the contents of AC1. 


(VAR (ор ac , varname)) | | | | 
| | | permits writing a machine instruction with the value of a variable as 
the operand. Generates the appropriate address and index fields to , 
reference the value of varname. varname may be a locally bound 
variable, free variable, globalvar, etc. (tc. Note that VAR may generate 
more than one instruction. | | 


(f) * js used to indicate a comment; the statement is ignored. 


69 Note that assemble macros produce a list of statements to be assembled, whereas compiler macros produce a single 
expression. An assemble macro which computes а list of statements begins with LAMBDA and тау be either spread ог 
no-spread. The analogous compiler macro begins with an atom, (ie. is always no-spread) and the LAMBDA is 


understood. 
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. There are several locations in the basic machine code of Interlisp-10 which may be referenced from 
compiled code. The current value of each location is stored on the property list under the property _ 
СОВЕМА |. . 79 Since these locations may change in different reassemblies of Interlisp-10, they аге 
written symbolically on compiled code files, 1.е., the name of the corresponding COREVAL 15 
written, not its value. Some of the СОКЕУАТ used frequently in assemble are: 


KT contains (pointer to) atom T 
KNIL contains (pointer to) atom NIL 
MKN routine to box an integer 

MKFN routine to box floating number . 


IUNBOX routine to unbox an integer 
FUNBOX routine to unbox floating number 


The index registers used for the push-down stack pointers are also included as COREVALS. These 
are not expected to change, and are not stored symbolically on compiled code files; however, they 
should be referenced symbolically in assemble code. They are: | | : 


PP parameter stack 
CP control stack | 
МР basic frame pointer 


18.15 LAP 

LAP (for LISP assembly Processor) бан: ше output of the first pass of compilation to produce 
numerical machine instructions. | 
LAP STATEMENTS 

Ifa LAP statement is an atom, it is treated as a label identifying the location of the next statement 
to be processed. If a LAP statement is not an atom, car of it must be an atom and one of the 
following: (1) a number; (2) a machine instruction; or (3) a LAP macro. 

(1) numbers 


If car of a LAP statement is a number, a location containing the ће is produced іп the коше 
сойе, 


70 The value of corevals is а list of all atoms with COREVAL properties, 
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e.g., (ADD 1 , A (1)) n 


E етді of this type are processed like machine instructions, with the initial number serving as a 
36-bit op-code. | | 


О) Machine Instructions 


If car of a LAP statement has a numeric value for the property OPD, 12 the statement is a machine 
instruction. The general form of a machine instruction is: | 


(opcode ac , @ address (index)) 
Op code is any PDP-10 instruction mnemonic or Interlisp UUO. n 


Ас, the accumulator field, is optional. However, if present, it must, be followed by a comma. Acis 
either a number or an atom with a COREVAL property. The ЮК order 4 bits of the number or 
 COREVAL аге ОК to the AC field of the instruction. 


@ may be used anywhere in the instruction to specify indirect е (bit 13 set in “tte 
instruction) e.g., (HRRZ 1 , @ 1 (VP)). | 


Address is the address field which may be any of the following: 


— constant Reference to an unboxed constant. A location containing the 
| unboxed constant will be created in a region at the end of the 
function, and the address of the location containing the constant is 
placed in the address ficld of the current instruction. The constant 
may be a number е.р., (CAME 1, = 3596); an atom with a 
property COREVAL (in which case the constant is the value of the 
property, at LOAD time); any other atom which is treated as a label | 
(the constant is then the address of the labeled location) e.g. 
(MOVE 1 , = TABLE) is equivalent to (MOVEI 1 , TABLE); 
or an expression whose value i is a number. | п 


: pointer The address is a reference to a Interlisp pointer, e.g., a list, number, 
| | string, etc. А location containing the pointer is assembled at the 


n Note that if a function is intended to be swappable (Section 3). it may not contain any relocatable, indexed 


instructions. 
72 Тһе value is an 18 bit quantity (rather than 9), since some UUO's also use the AC field of the instruction. - 
B The TENEX JSYS's are not defined, that is, one must write (JSYS 107) instead of (KFORK). 
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end of the дабот апа Фе сштеп{ instruction will have the 
address of this location, 

eg. (HRRZ 1, ' "IS NOT DEFINED") 

(НАВ 1 , " (NOT FOUND)) 


* | Specifies the current location іп Ше compiled function; e.g., 
| (JRST * 2) has Ше same effect as (5КІРА). 


literal atom | If the atom has а property COREVAL, it is a reference to a system 
| location, е.р., (SKIPA 1, KNIL), and the address used is the 
value of the coreval. Otherwise the atom is a label referencing a 

location in the LAP code, e.g., (JRST А). 


number | The number is the address: e.g., 
(MOVSI 1 , 4000000) 
(HLRZ 2 , 1 (1)) 


list | The form is evaluated, and its value is the address. | 


Anything else in the address field causes an error message, e.g., (SKI PA 1 „ KNILL) - 
LAPERROR. A number may follow the address беја and will be added to it, e.g., (JRST А 2). 


Index is denoted by a list following the address field, 1.е., the address field must be present if an 
index field is to be used. The index саг of the list) must be either а number, or an atom with a 
property COREVAL, eg, (HRRZ 1, 0 (1)). | 


(3) LAP macros 


If car of a LAP statement is the name of a LAP macro, і.е., has the property OPD, the statement is 
a macro call. The arguments of the call follow the macro name: e.g., (102 ЕТЕ 3). 


LAP macro calls comprise most of the output of the first pass of the compiler, and may also be 
used in assemble. The definitions of these macros are stored on the property list under the 
property OPD, and like assembler macros, may be either lambda or substitution macros. In the 
first case, the macro definition is applied to the arguments of the call; 74 in the second case, the 
arguments of the call are substituted for occurrences of the dummy symbols in the definition. In 
both cases, the resulting list of statements is again processed, with macro expansion continuing till 
the level of machine instructions is reached. | 


Some examples of LAP macros are shown іп Figure 18-2. 


74 


The arguments were already evaluated in the first pass, sce page 18.25, 
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| (DEFLIST(QUOTE( | | 
(LQ ((X) (* LOAD QUOTE TO AC1) 
. (HRRZ 1, 'X))) 
(102 ((Х AC) | (* LOAD QUOTE TO AC) 
A (HRRZ АС, " X))) Е 
(LDV ((A SP) mE .(* LOAD LOCAL VARIABLE TO АС1) 
(HRRZ 1 , (VREF A SP)))) 721 | 
(STV ((A SP) | (* SET LOCAL VARIABLE FROM АС1) 
| (HRRM 1 , (VREF А SP)))) | | | | 
(LDV2 ((А SP АС) |  (* LOAD LOCAL VARIABLE ТО AC) 
| . (HRRZ AC , (VREF А 5Р)))) | 
(LDF ((A SP) | | (* LOAD FREE VARIABLE TO AC1) 
(HRRZ 1 , (FREF A SP)))) 2 Е | 
(STF ((A SP) Ер | (* SET FREE VARIABLE FROM АС1) 
(HRRM 1 , (FREF A SP)))) | 
_ (LDF2 ((А SP) | | = (* LOAD FREE VARIABLE TO AC) 
~ (HRRZ 2 , (FREF A 5Р)))) | 
(САВА (NIL _ (* САВ ОЕ АС1 ТО АС1) 
(HRRZ 1 , 0 (1)))) 
(CDR1 (NIL (* CDR OF АС1 TO AC1) 
_ (HLRZ 1, 0 (1)))) | | ОИС 
(CAR2 ((АС) (* САК ОҒ АС ТО АС) 
| (HRRZ AC ‚ 0 (AC)))) 
(CLL ((МАМ М) | | (* CALL FN WITH М ARGS GIVEN) 
(CCALL М , " МАМ))) | Е 
(LCLL ((NAM М) (* LINKED CALL WITH N ARGS) . 
(LNCALL N , (MKLCL NAM)))) | пра, 
(RET (NIL _ (* RETURN FROM FN) 
| (РОРЈ СР ,) | 
(PUSHP (NIL (PUSH PP , 1))) 
 (PUSHQ ((X) | (* PUSH QUOTE) 
(PUSH PP , " X))) 
))(QUOTE OPD)) | | 
Figure 18-2 
Examples of LAP Macros 


Using Assemble 


18.16 USING ASSEMBLE 


· In order to use assemble, it is helpful to know the following things about how compiled code 15 
run. All variable bindings and temporary pointers are stored on the parameter pushdown stack 
(addressed by index register PP). Control information is stored on the control pushdown stack 
(addressed by index register, CP). A function call proceeds as follows: | | | 


1. Тһе calling function pushes the argument values on the parameter stack, 


2. Тһе calling function invokes a routine that adjusts the number of arguments if too few or too > 
| тапу ите supplied, and binds the загине, Binding нш а the creation of a basic 
frame. | 


33 | Then the called function is Hn 


The arguments in the basic frame are referenced relative to index register VP, e.g., 1(МР) 
addresses the first argument. However, it is better to reference variables in less implementation 
dependent ways, such as (СО ...) or (VAR ( ... )). The compiler will then generate the 
correct code whether the variable is bound locally, is а free reference, is a globalvar, etc. 


The parameter stack may be used for temporary storage of pointers. Both halves of a word on the 
parameter stack may be pointers. On the control stack the right half of a word must be a pointer, 
the left a non-pointer. Anything else can cause the garbage collector to fail. | 


For temporary storage of unboxed numbers, the following assemble macros are poe 


( PUSHN addr) "Pushes" the number ко by addr, “addr may be any ща | | 
| assemble code address field, for example: EM Tu 
(PUSHN 1), (PUSHN = ! 0), (PUSHN @ 2) 


(POPN addr) "Pops" the most recent number to addr. 


(NREF (op ac , n)) References a previously pushed number. ор is the opcode, ac is _ 
the accumulator, n is the relative position of the desired number on 
the pseudo number stack. That is, п - 0 refers to the most recent 
number, n = -1 to the next most recent, etc. For example: 

(NREF (MOWN 1; 1) | 


(PUSHNN пу 12...) "Pushes" a sequence of иша specified by nj where п, is a list 
of any legal address field. For example: 5 
(PUSHNN (1) (2) (= 0)) | 
pushes the contents of АС1, the contents of AC2, and the constant 


(РОРММ п) "Pops" the n most recent numbers, discarding the values. 


75 Whether a basic frame is created for a prog or open lambda depends on whether any of the variables are specvats. 


Sce page 18.18. 
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Use of these macros is subject to the following restrictions: 


be + PUSHN's and POPN's must be seen by the compiler in the same order and number in which 
they are executed. The compiler does not analyze the code; it assumes when it encounters а 
PUSHN in the sequential processing of the code that the PUSHN will in fact be executed. 


2. Every number that is pushed must be popped. | 

3. Та nested assemble statements, if a prog or open lambda occurs between the inner and outer 
level assemble, numbers pushed in the outer. assemble m may not be referenced from the inner 
assemble. | 


18.17 MISCELLANEOUS 


The value of a function is always returned іп АС1. Therefore, the pseudo-function, ac, 15 available 
for obtaining the current contents of AC1. For example (СО (FOO (AC))) compiles a call to 
FOO with the current contents of AC] as argument, and is equivalent to: 


(PUSHP) 0 
(Е (PSTEP)) _ 
(CLL (QUOTE F00) 1) 
(E (PSTEPN -1)) 


Та using ас, be sure that it appears as the first argument to ре схашаке іп the expression. For 
example: (CQ (IPLUS (LOC (AC)) 2)) 2 


There are several ways to reference the values of variables in assemble code. For example: 


to put value of X in ACI: | (СО Х) 

to put value of X in АСЗ: | (LDV2 (QUOTE X) SP 3) 
to set X to contents of ACI: | |... (SETQ X) 

to set X to contents of AC2: С (VAR (НААМ 2, X)) | 


to box and unbox a number: 


(CQ (LOC (AC))) box contents of АС1 | 
(FASTCALL MKFN) floating box contents of АС1 
(CQ (VAG X)) | unboxed value of X to АС1 
башы FUNBOX) floating unbox of АС1 


To cati a function directly, the arguments must be pushed on the parameter stack, and SP must be 
ше and then the function called: e.g., | 


(СО (САК Х)) 
(PUSHP) | (* stack first argument) 
(E (PSTEP)) | | 
(PUSHQ 3.14) 
(Е (PSTEP)) | (* stack sccond argument) 
18.32. 
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(CLL (QUOTE FUM) 2) (* call FUM with 2 arguments) 
(Е (PSTEPN -2)) | (* adjust stack count) 


and is equivalent to: 


(CQ (FUM (CAR X) 3.14)) 


18.18 COMPILER PRINTOUT AND ERROR MESSAGES 
For cach function compiled, whether from tcom mpl, г ecompile, or com трпе, {һе FOIS prints: | 


(fn (arg) ... arg,) (free; .. ‚ free) 


The message is printed at the beginning of the second pass of the compilation of fn. (arg; ... arg ) 
is the list of arguments to fn, and (free, ... Пее) the list of Пее variables referenced or set in 126 
The appearance of non-variables, e. g., function names, words from a comment, etc. in 
(free, ... free,) is a good indication of parenthesis errors. и А 


If the compilation of fn causes the generation of. one or more gensym m functions (see page 18. 13), а 


compiler message will be printed for these functions before the message for fn, ер. 


(FOOA0027 NIL (X)) 
(FOO (X) NIL) 


When compiling a block, the compiler first prints (blkname blkfnl bikfn2 ...). Then the normal 


message is printed for the entire block.” Then a message is printed for each entry to the block. 


In addition to the above output, both recompile and brecompile print the name of each function 
that is being copied from the old compiled file to the new compiled file. The normal compiler 
message is printed for each function that is actually compiled. | 


Compiler output and errormessages go to the file coutfile, initially T. coutfile can also be set to the 
name of a file opened for output, in which case all compiler output will go to coutfile, i.e. the 
compiler will compile "silently." However, any error messages will be printed to both coutfile as 
well as T. | | 


COMPILER ERROR MESSAGES 


Messages describing errors in the function being compiled are also printed on the teletype. These 
messages are always preceded by *****. Unless otherwise indicated below, the compilation will 
continue. | 


(fn МОТ ОМ FILE, COMPILING IN CORE DEFINITION) 
from calls to bcompl and brecompile. - : 


76 Does not include global variables, see page 18.4. 


7 The names of the arguments to the block are generated by suffixing "Ж" and а | number to the block name, e.g., 


(FOOBLOCK (FOOBLOCK #0 FOOBLOCK #1) free-variables). 
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(fn МОТ COMPILEABLE) | p 
An expr definition for fn could not be found. In this case, no code is өйне Гог fn, and 
. the compiler proceeds to the next function to be compiled, if any. 


(fn NOT FOUND) Е 
Occurs when recompile ог brecompile try to copy the compiled definition of fn Жош cfile, | 
and cannot find it. In this case, по code is copied апа the compiler proceeds to | the 
next function to be compiled, if any. 


(fn NOT ON BLKFNS) 
fn was specified as an entry to a block, or е маѕ оп blkapplyfns, but did not appear on 


the blkfns. In this case, no code is produced for the entire block and the аре кле, 


proceeds t to the next function to be compiled, if any. 


(fn CAN'T BE BOTH AN ENTRY AND THE BLOCK NAME) Е 
In this case, по code is produced for the entire block and the шр proceeds to the next 
. function to be compiled, if any. 


(blkname - USED BLKAPPLY WHEN NOT APPLICABLE) 
blkapply is used in the block blkname, but there are no Марр ог г entries 5 declared. for 
the block. 


(var SHOULD BE A SPECVAR - USED FREELY BY fn) ЕКО | 
In Interlisp-10, while compiling а block, the compiler has already — года to bind _ 

var as a LOCALVAR, but now dicovers that fn uses var пре уаг should be declared a 
SPECVAR and the block recompiled. ИЕ 


(С. --) COMMENT USED FOR VALUE) | 
а comment appears in a context where its value is being used, e.g. (LIST X С“ --) Y). Тһе 
compiled function will run, but the value at the point where the comment was used is 
"undefined." 


((form) - NON-ATOMIC CAR OF FORM) 
ТЕ user intended to treat the value of form as a function, he should use apply*. form is 
. compiled as if apply* had been used. d. See Section 8. 


((SETQ var expr --) -BAD SETQ) 
setq of more than two arguments. 


(fn- USED AS ARG TO NUMBER ЕМ?) 
| Тһе value of a predicate, such as GREATERP or EQ, is used. as an argument to a function 
that expects numbers, such as IPLUS. 


(fn - NO LONGER INTERPRETED AS FUNCTIONAL ARGUMENT) 
- The compiler has assumed fn is the name of a function. If the Aer intended to treat the 
value of fn as a function, he must usc a apply*. Sce Section 8.78 | 


(fn - ILLEGAL RETURN) 


This message is printed when fn is not defined, and is also a local variable of the function being compiled. Note that | 
earlier versions of the Interlisp-10 compiler did treat fn as a functional argument, and compiled code to evaluate it. 
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return encountered when not in prog. 


(tg - ILLEGAL GO) | 
go encountered when not in a prog. 


(tg - MULTIPLY DEFINED TAG) 
tg is a PROG label that is defined more than once in a single PROG. The second definition 
is ignored. | | 


(tg - UNDEFINED TAG) 
tg is a PROG label that is referenced but not defined in a PROG. 


(var - NOT А BINDABLE VARIABLE) + 
var 15 NIL, Т, or else not a literal atom. + 
(var val -- BAD PROG BINDING) | + 
occurs when there is a prog binding of the form (var val, ... valp. + 
(tg - MULTIPLY DEFINED TAG, ASSEMBLE) 
tg is a label that is defined more than once in an assemble form. 
(tg - UNDEFINED TAG, ASSEMBLE) 
tg is a label that is referenced but not defined in an ASSEMBLE form. 
(tg - MILTIPLY DEFINED TAG, LAP) 
tg is a label that was encountered twice during the second pass of the compilation. If this 
error occurs with no indication of a multiply defined tag during pass one, the tag is in 
а ГАР macro. | 
(ір - UNDEFINED TAG, LAP) 
tg is a label that is referenced during the second pass of compilation and is not defined. | 
LAP treats tg as though it were a coreval, and continues the compilation. 
(op - OPCODE? - ASSEMBLE) 
Op appears as car of an assemble statement, and is illegal. See page 18.24-26 for legal 
assemble statements. 
(NO BINARY CODE GENERATED OR LOADED FOR fn) + 
a previous error condition was sufficiently serious that binary code for fn cannot be loaded + 
without causing an error. | | + 
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SECTION 19 
ADVISING! 


The operation of advising gives the user a way of modifying a function without necessarily knowing 


how the function works or even what it does. Advising consists of modifying the interface between 
functions as opposed to modifying the function definition itself, as in editing. break, trace, and 


breakdown, are examples of the use of this technique: they cach modify user functions by placing 


relevant computations between the function and the rest of the programming environment. 


The principal advantage of advising, aside from its convenience, is that it allows the user to treat 
functions, his or someone else's, as "black boxes," and to modify them without concern for their 
contents or details of operations. For example, the user could modify sysout to set sysdate to the 
time and date of creation by advise[SYSOUT;(SETQ SYSDATE (DATE))] > 


As with break, advising works equally well on compiled and interpreted functions. Similarly, it is 
possible to effect a modification which only operates when a function is called from some other 
specified function, ie. to modify the interface between two particular functions, instead of the 
interface between one function and the rest of the world. This latter feature is especially useful for 
changing the internal workings of a system function. 


For example, suppose the user wanted time (Section 21) to print the results of his measurements to 
the Ше FOO instead of the teletype. He | could accomplish this by 
ADVISE(((PRIN1 PRINT SPACES) IN TIME) BEFORE (5ЕТОО U ЕОО)) 


Note that advising prinl, print, or spaces directly would have affected all calls to these very 
frequently used function, whereas advising ((PRIN1 PRINT SPACES) IN TIME) affects just 
those calls to prinl, print, and spaces from time. 


Advice can also be specified to operate after a function has been evaluated. The value of the body - 


of thc original function can be obtained from the variable !value, as with breakl. For example, 
suppose the user wanted to perform some computation following each sysin, e.g., check whether his 
files were up to date. He could then: | 


ADVISE(SYSOUT AFTER (COND ((LISTP !VALUE) --)))? 


Advising was developed and implemented Бу W. Teitelman. 


sysin. See Section 14 for complete discussion of sysout/sysin. 
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After the sysin, the system will be as it was when the sysout was performed, hence the advice must be to sysout, not . 
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19.1 IMPLEMENTATION OF ADVISING _ 


The structure of a function after it has been modified several times by advise is given in the 
following diagram: 


ADVICE 1 


ADVICE 
BEFORE 


MODIFIED 
. FUNCTION 


ORIGINAL 
FUNCTION 


ADVICE 
AFTER 


FIGURE 19-1 
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The corresponding Interlisp definition is: 


(LAMBDA arguments (PROG (!VALUE) 
(SETQ ! VALUE (PROG; NIL 


advicel 
advice 
_ before 
advicen 
(RETURN body) ) ) 
advicel = 
advice | 
after 
advicem 


(RETURN !VALUE))) 


where body is equivalent to the original definition. 4 


_ Note that the structure of a function modified by advise allows a piece of advice to bypass the 


original definition by using the — function RETURN. For example, if 
(COND ((ATOM X) (RETURN Y))) were one of the pieces of advice BEFORE a function, and 
this function was entered with x atomic, y would be returned as the value of the inner PROG, 
!value would be set to y, and control passed to the advice, if any, to be executed AFTER the 
function. If this same piece of advice appeared AFTER the function. y would be returned as the 
value of the entire advised function. | 


Тһе advice (COND ((ATOM X) (SETQ !VALUE Y))) AFTER the function would have a similar 
effect, but the rest of the advice AFTER the function would still be executed. 


19.2 ADVISE FUNCTIONS 
ADVISE 


Advise is a function of four arguments: fn, when, where, and what. fn is the function to be 


modified by advising, what is the modification, or piece of advice. when is cither BEFORE, AFTER, 
or AROUND, and indicates whether the advice is to operate BEFORE, AFTER, or AROUND the body 


of the function definition. where specifies exactly where in the list of advice the new advice is to- 


be placed, е.р., FIRST, or (BEFORE PRINT) meaning before the advice containing print, or 
(AFTER 3) meaning after the third piece of advice, or even (: TTY:). If where is specified, 
advise first checks to see if it is one of LAST, BOTTOM, END, FIRST, or TOP, and operates 
accordingly. Otherwise, it constructs an appropriate edit command and calls the editor to insert the 
advice at the corresponding location. 


Both when and where arc optional arguments, in the sense that they can be omitted in the call to 


advise. In other words, advise can be thought of as a function of two arguments [fn;what] or а. 


3 Actually, advise uses its own versions of PROG, SETQ, and RETURN, “(called ADV-PROG, ADV-SETQ, and 


ADV-RETURN) in order to enable advising these functions. 


If fn was originally an EXPR, body is the body of the definition, otherwise a form using a gensym which is defined 
with the original definition. : 
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function of three arguments: [fn;when;what], or а function of four arguments: 
[fn; when;where;what]. Note that the advice is ши the last argument If when=NIL, BEFORE 
is used. If where=NIL, LAST is used. 


advisef fn: when: where: what] 


fn is the. function to be advised, when=BEFORE, AFTER, or 
AROUND, where specifies where in the advice list the advice is to be 


inserted, and what is the piece of advice. 


If fn is of the form (бо! IN бо), fal is changed to fnl-IN-fn2 - 


throughout fn2, as with break, and then fnl- IN-fn2 is used in- 


place of fn. С 


If fn is broken, it is unbroken before advising. 


If fn is not defined, an error is аза NOT A FUNCTION. 


If fan is being advised for the first time, ie, if 


getp[name, ADVISED]=NIL, а gensym is generated and stored on 
the property list of fn under the property ADVISED, and the 
gensym is defined with the original definition of hi An 
appropriate S-expression definition is then created for fn. > Finally, | 
fn is added to the (front of) advisedfns.’ 


If fn has been advised before, it is moved to the front of 
advisedfns. | 


If when=BEFORE or AFTER, the advice is inserted іп fn's 
definition either BEFORE or AFTER the original body of the 
function. Within that context, its position is determined by where. 
ЈЕ wherez LAST, BOTTOM, END, or NIL, the advice is added 
following all other advice, if any. If мћеге= FIRST ог TOP, the 
advice is inserted as the first piece of advice. Otherwise, where is 
treated as a command for the editor, a Та breakin, ер, 
(BEFORE 3), (AFTER PRINT) . 


If when = AROUND, the body is substituted for * in the advice, and - 


the result becomes the new body, e.g., 
advise[F00; AROUND; (RESETFORM (OUTPUT T) *)]. Note that 
if several pieces of AROUND advice are specified, earlier ones will be 
embedded inside later ones. The value of where is ignored. 


Finally list[when;where;what] is added (by addprop) to the value of 


If fnl and/or fn2 are lists, they are distributed as shown in the example on page 19.1. 
Using private versions of PROG, SETQ, and RETURN, so that these functions can also be advised. 


· So that unadvise[ T] always unadvises the last function advised. Sce page 19.5. 
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property ADVICE on the property list fn. Note that this property 
value is a list of the advice in order of calls to advise, not 
necessarily in order of appearance of the advice in the definition of 
fn. | 


The value of advise is fn. 


If fn is non-atomic, every function in fn is advised with the same 
values (but copies) for when, where, and what. In this case, the 
value of advise is a list of individual functions. | 


Note: advised functions can be broken. (However if a function is broken at the time it is advised, 
it is first unbroken.) Similarly, advised functions can be edited, including their advice. unadvise 
will still restore the function to its unadvised state, but any changes to the body of the definition 
will survive. Since the advice stored on the property list is the same structure as the advice 
inserted in the function, editing of advice can be performed on either the function's definition or 
its property list. 


unadvisel[x] | is а no-spread NLAMBDA а la unbreak. It takes an indefinite 
| number of functions and restores them to their original unadvised 
state, including removing the properties added by advise? unadvise 
saves on the list advinfolst enough information to allow restoring a 
function to its advised state using readvise. advinfolst 209 readvise 
thus correspond to brkinfolst and rebreak. 


unadvise[] unadvises all functions on advisedfns.! It first sets 
advinfolst to NIL. 


unadvise[ T] unadvises the first function of advisedfns, ie. the 
most recently advised function. 


readvise[x] | is a no-spread NLAMBDA a la rebreak for restoring a function to its 
advised state without having to specify all the advise information. 
For each function on x, readvise retrieves the advise information 
either from the property READVICE for that function, or from 
advinfolst, and performs the corresponding advise operation(s). In 
addition it stores this information on the property READVICE if not 
already there. If no information is found for a particular function, 
value is (fn - NO ADVICE SAVED). 


readvise[] readvises everything on advinfolst. 


So that a record of all the changes is available for subsequent use in readvising, see page 19.5. 


Except if a function also contains the property READVICE (see readvise below), unadvise moves the current value of 
the property ADVICE to КЕАОУІСЕ; 


10 


In reverse order, so that the most recently advised function is unadvised last. 
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readvise[ T] readvises just the first function on advinfolst, i.e., the 
function most recently unadvised. 


A difference between advise, unadvise, and readvise versus break, unbreak, and rebreak, is that if a 
function is not rebroken between successive unbreak[]’s, its break information is forgotten. 
However, once readvised, a function’s advice is permanently saved on its property list 
(under READVICE); subsequent calls to unadvise will not remove it. In fact, calls to unadvise 
update the property READVICE with the current value of the property ADVICE, so that the 
sequence readvise, advise, unadvise causes the augmented advice to become permanent. Note that 
the sequence readvise, advise, readvise removes the "intermediate advice" by restoring the function 


to its earlier state. 


advisedump[x:flg] 


Used by prettydef when given a command of the form (ADVISE --) 
or (ADVICE --). flg=T corresponds to (ADVISE --), іе, 
advisedump writes both a deflist and а readvise. flg=NIL 


corresponds to (ADVICE --) ie. only Ше deflist is written. In 


either case, advisedump copies the advise information to the 


property READVICE, thereby making it "permanent" as described 


above. 
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SECTION 20 
MASTERSCOPE AND HELPSYS 


20.1 MASTERSCOPE! 


Masterscope is an interactive program for analyzing and cross referencing user programs. It 
contains facilities for analvzing user functions to determine what other functions are called, how _ 
and where variables are bound, set, or referenced, as well as which functions use particular record 
declarations. Masterscope is able to analyze definitions directly from a file as well as in-core 
definitions. | | 


Masterscope maintains a database of the results of the analyses it performs. Via a simple command 
language, the user may interrogate the database, call the editor on those expressions in functions 
that were analyzed which use variables or functions in a particular way, or display the tree 
structure of function calls among any set of functions. 


Masterscope is interfaced with the editor and file package so that when a function is edited ог а 
new definition loaded in, Masterscope knows that it must re-analyze that function. 


The following sample session illustrates some of these facilities, User input 1s underlined. 


Masterscope was designed and implemented Бу L. M. Masinter. 
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.. MASTERSCOPE | 
» Masterscope 1-ЈАМ-76 ... 
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€. ANALYZE FUNCTIONS ON RECORD? 
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ә е ө ө е 9 е е е е в е ә е е е е е 9 еее о 


NIL 
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SHOW PATHS ТО RECFIELDLOOK FROM ACCESSDEF2 


1.RECFIELDLOOK RECFIELDLOOK 
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5. 
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ACCESSDEF — 
ACCESSDEF2 ACCESSDEF2 
ACCESSDEF 
RECORDCHAIN ACCESSDEF | 


WHO CALLS WHO IN /FNS2 
RECORDSTATEMENT -- /RPLNODE 


RECORDECL1 -- /NCONC, /RPLACD, /RPLNODE 
RECREDECLARE1 -- / PUTHASH 

UNCLISPTRAN -- /PUTHASH, /RPLNODE2 
RECORDWORD -- /RPLACA | 

RECORD1 -- /RPLACA, /SETTOPVAL 
EDITREC -- /SETTOPVAL 

e. oi 


Figure 20-1 
Sample Masterscope Session : 
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type HELP<cr> for command summary. 
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Masterscope 


n 


The user calls masterscope directly. Masterscope prints a greeting and prompts with "e 
Within the top-level executive of Masterscope, the user may issue Masterscope commands, 
programmer’s assistant commands, (e.g., REDO, FIX), or run programs. 


The user then directs that the functions on file RECORD should be analyzed. Masterscope - 


always prints a . when it (re)analyzes a function, just to let the user know what is happening. 
The user asks which functions call recfieldlook. Masterscope responds with the list. 


The user asks to edit the expressions where the function recfieldlook is called. Masterscope 
calls editf on the functions it had analyzed that call recfieldlook, directing the editor to the 


appropriate expressions. The user then edits some of those expressions, 


Next the user asks which functions call error. Since some of the (icons. in the dabas 
have been changed, Masterscope re-analyzes the changed definitions (and prints out .’s for 
each function it analyzes). Masterscope responds that editrec is the only analyzed function 
that calls error. | | EET 


The user asks to see a map of the ways in which recfieldlook is called from accessdef. A tree 
structure of the calls is displayed. 


The user then asks to see which functions call which functions in the list /fns. Masterscope 
responds with a structured printout of these relations. 


Finally, the user exits from the Masterscope сай with an OK. | 


20.1.1 COMMAND LANGUAGE 


The user communicates with Masterscope via an English-like command language. Through. these 
commands, the user can direct that functions should be analyzed, interrogate Masterscope’s 
database, and perform other operations. The commands deal with sets of functions, variables, etc., 
and relations between them (e.g., call, bind). Sets correspond to English nouns, relations to verbs. 


A set of atoms can be specified in a variety of ways, either explicitly, е.р., FUNCTIONS ON FIE 
specifies the atoms in filefnslst[FIE], or implicitly, e.g., NOT CALLING У, where the meaning must 
be determined in the context of the rest of the command. Such sets of atoms are the basic building 
blocks which the command language deals with. 


Masterscope also deals with relations between sets. For example, the relation CALL relates functions 


Note that the user may also enter Masterscope commands directly from the top-level of Interlisp (or from within a 
break or in the editor, etc.) merely by preceding the command with a period and a space. The atom . is defined as 
a nlambda nospread function which interprets its argument as a Masterscope command, executes the command and 
returns. | 


The fcedback when Masterscope analyzes a function is controlled by the flag msprintflg: if msprintflg is the atom 
",“, Masterscope will print out a period. (If an error in the function is detected, а ? is printed instead.) If msprintflg 
is a number, Masterscope will print the name of the function it is analyzing every nth function. If msprintflg is NIL, 
Masterscope won't print anything. Initial setting is ".". Note that the function name is printed when меш 
starts analyzing, and the comma is printed when it finishes, | | 
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and other functions; the relations BIND and USE FREELY relate functions and variables. The 
relations are what are stored in the Masterscope database when functions are analyzed. In addition, 
Masterscope "knows" about file package conventions; CONTAIN relates files and various types of 


| obj ects (functions, variables). 


Sets and relations are used (along with a few additional words) to form sentence-like commands. 
For example, the command WHO ON 'FOO USE 'X FREELY will print out the list of functions 
contained in the file FOO which use the variable X freely. The command EDIT WHERE ANY CALL 
"ERROR will call editf on those functions which have previously been analyzed that directly call 
error, pointing at each successive expression where the call to error actually occurs. 


RELATIONS 


- A relation is specified by one of the keywords below. Some of these "verbs" accept modifiers. For 


example, USE, SET, SMASH and REFERENCE all may be modified by FREELY. The modifier | 


gay occur anywhere within the command.* Verbs can occur in the present tense (e.g. USE, 


CALLS, BINDS, USES) or as present or past participles (e.g, CALLING, BOUND, TESTED). 
The relations (with their modifiers) recognized by Masterscope are: 


CALL . Function F1 calls F2 if the definition of F1 contains a form | 
| | (F2 --), (APPLY (QUOTE F2) --), (FUNCTION F2), etc. 


CALL SOMEHOW  — One function calls another SOMEHOW if there is some path from the | 
first to the other. That НА if F1 calls F2, and F2 calls F 3, then 
Fi CALLS F3 SOMEHOW.° 


USE | | If unmodified, the relation USE denotes variable usage in any Way: | 


it is the union of the relations SET, SMASH, TEST, and 
REFERENCE. | 
SET ое A function SETS a variable if the function contains a fom 


(SETQ var --), (SETQQ var --), etc. 


SMASH А бй бй SMASHES а variable if the function calls a destructive 
| list operation (rplaca, rplacd, dremove, sort, etc.) on the value of 
that variable. Masterscope will also find instances where the 
operation is performed on a "part" of the value of the variable; for 
example, if a function contains a form (RPLACA (NTH X 3) T) 
it will be noted as SMASHING x, 5 


4 If there is more than one verb, any modifier between two verbs is assumed to modify the first one. For example, in 
USING ANY FREELY OR SETTING X, the FREELY modifies USING but not SETTING-- the entire phrase is 
interpreted as the set of all functions which either use any variable freely or set the variable X, whether or not X is 
bound in the place where it is set. | 

> This information is not stored directly in the database; instead, Masterscope stores only information about direct 


function calls, and (re)computes the CALL SOMEHOW relation as necessary. 


e, Note, however, that if the function contains a sequence (SETQ Y X) (RPLACA Y T) then Y is noted as being 
| smashed, but not Х. 
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TEST 


REFERENCE 


Masterscope Command Language 


A variable is TESTED by a function if its value is only 
distinguished between NIL and non-NIL. For example, the form 
(COND ((AND X --) --)) tests the value of X. 


This relation includes all variable usage except for SET. 


The verbs USE, SET, SMASH, TEST and REFERENCE may be modified by the words FREELY 


ог LOCALLY.A variable is used FREELY if it is not bound in the function at the place of its use; 


alternatively, it is used LOCALLY if the use occurs within a PROG or LAMBDA that binds the 


variable. 


Masterscope also distinguishes 
called DIRECTLY if it occurs 


between CALL DIRECTLY and CALL INDIRECTLY. A function is- 


as car-of-form in a normal evaluation context. A function is called 


INDIRECTLY if its name appears in a context which, does not imply its immediate evaluation, for 
example (ФЕТО Y (LIST (FUNCTION FOO) 3))'. In addition, CALL FOR EFFECT (where 
the value of the function is not used) is distinguished from CALL F OR VALUE.. 


BIND 


USE AS A FIELD 


FETCH 
REPLACE 


USE AS A RECORD 


CREATE 
USE AS A PROPERTY NAME 
USE AS A CLISP WORD 


CONTAIN 


an occurrence of (FUNCTION 


The BIND relation between functions and variables includes both - 
variables bound as arguments and those bound in an internal prog. 


or lambda. 


Masterscope notes all uses of record field Бле within fetch, | 


replace or create expressions. 
Use of а field within a fetch expression. 
Use of a record field name within a replace or create expression. 


Masterscope notes all uses of record names within create or type? 
expressions. 


Use of a record name within a create expression. 


Masterscope notes the property names used in getprop, putprop, 
getlist, etc. expressions if the name is quoted. E.g. if a function 
contains a form (GETPROP X (QUOTE INTERP)), then that 
function USES INTERP AS A PROPERTY NAME. 


Masterscope notes all iterative statement operators and user defined. 


clisp words as being used as a clisp word. 


Files contain functions, records, and variables. This relation is not 
stored in the database but is computed using the file package. 


The distinction is whether or not the compiled code of the caller would contain a direct call to the callee. Note that 


FOO) as the functional argument to one of the built-in mapping functions which 


compile open is considered to be a direct call. 


Additionally, in X: 200. ЕТЕ, FOO is used as a record пате, 
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DECLARE AS LOCALVAR | к", 
DECLARE AS SPECVAR Masterscope notes internal "calls" to DECLARE from within 
ШЕ functions. | 


Note: Masterscope uses "templates" for functions, as described on page 20.16, to decide which 
relations hold. For example, the information that sort SMASHes its first argument is contained in 
the template for SORT. Masterscope initially contains templates for most system functions which set 
variables, test their arguments, or perform destructive operations. The user may change existing 
. templates or insert new ones in Masterscope’s tables via the 5 settemplate function, described on 
page 20.18. 


The following  Aabbreviations are recognized: | FREE- FREELY, | LOCAL» LOCALLY, 
PROP=PROPERTY, REF=REFERENCE. Also, the words A, AN and NAME (after AS) are “noise” 
words and may be omitted. | 


SETS 


A "set" is a collection of things (functions, variables, etc.). A set is specified by a set phrase, 
consisting of a determiner (е.р., ANY, WHICH, WHO) followed by a type (e.g, FUNCTIONS, 
VARIABLES) followed by a specification (е.р., IN MYFNS, 8 SUBRP). The determiner, type and 
specification may be used alone or in combination. For example, ANY FUNCTIONS IN MYFNS, 
ANY @ SUBRP, VARIABLES IN GLOBALVARS, and WHO are all acceptable | set с set 
аланы types and determiners аге explained below: 


Set specifications 


‘atom . The simplest way to specify а set consisting of a single thing is by 
. the name of that thing. For example, in the command WHO CALLS 
' ERROR, the function error is referred to by its name. Although the | 
' can be left out, to resolve possible ambiguities names should 
. usually be quoted; е.р., МНО CALLS 'CALLS will return the list of 
functions which call calls. 


' list | Sets consisting of several atoms may also be referred to by naming 
the atoms; e.g. the command WHO USES '(A B) will call the 
editor on all expressions where the variables A or B are used freely. 


IN expression Similarly, the user can give a LISP expression to be evaluated, and 
have the value treated as a (list of) the elements of a set. For 

example, IN GLOBALVARS specifies the list of ушаш їп the | 

value of globalvars. | 


@ predicate A set may also be specified by giving a predicate which the 
| elements of that set must satisfy. predicate is cither a function 
name, a LAMBDA expression, or an expression in terms of the 

variable X. The specification @ predicate represents all atom for 

which the valuc of predicate is non-NIL. For example, @ EXPRP 

specifies all those atoms which have expr decfintions; 0 

(STRPOSL X CLISPCHARRAY) specifies those atoms which | 

contain clisp characters. The universe to be searched is cither 
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determined by the context within the command (ер. in WHO IN 
FOOFNS CALLS ANY NOT @ GETD, the predicate is only applied 
to functions which are called by any functions in the list FOOFNS), 
or in the extreme case, the universe defaults to the entire set of 
things which have been noticed by Masterscope, as in the command 
WHO IS @ EXPRP. 


. atom may КЕНІН alt-modes; it is used as a pattern to be matched 


(as in the editor). For example, WHO LIKE /R$ IS CALLED BY 
ANY would find both /RPLACA and /RPLNODE. 


A set may also be specified by giving a relation its members must have with the members of 


another set: 


relationING set 


relationED BY set 


relationING is used here generically to mean any of the relation 
words in the present participle form (possibly with a modifier), e.g., 


USING, SETTING, CALLING, BINDING. relationING set 
. specifies the set of all objects which have that relation with some 


element of set. For example, CALLED BY X specifies the set of 
functions called by the function X; USING ANY IN FOOVARS 


FREELY specifies the set of functions which uses freely any. variable - 


in the value of FOOVARS. 


This is similar to the relationING construction. For example, 


CALLED BY. ANY ІМ FOOFNS represents the set of functions | 
22 which are called by any element of FOOFNS; USED FREELY BY. 


ANY CALLING ERROR is the set of variables which are used freely 
by any function which also calls the function error. IN may be used 
instead of BY, i.e., relationED IN set is allowed. 


Note: sets may also be specified with "relative clauses" introduced by the word THAT, eg. THE 


FUNCTIONS THAT BIND 


blocktype OF functions 
blocktype ON files 


FIELDS OF set 


These phrases allow the user to ask about BLOCKS declarations on 
files (see Section 18). blocktype is one of LOCALVARS, 
SPECVARS, GLOBALVARS , ENTRIES, |  BLKFNS, 
BLKAPPLYFNS, or RETFNS. These phrases denote the names 
which are declared to be blocktype in any blocks declaration which 
contain the any of functions (a "set" of functions). The function can 
either be the block name or just onc of the functions in the block. 


In the second construct, all names which are declared to be 


blocktype on any of the given files (a "set" of files) are denoted. 
For example, WHICH ENTRIES OF ANY CALLING "У BIND 
ANY GLOBALVARS ON 'FOO. 


set is a set of records. This denotes the field names of those 


rccords. 
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KNOWN — The set of all functions which have been analyzed. For example, 


the command WHO IS KNOWN will print out the list of functions 
which have been analyzed. 


THOSE | The set of things printed ош by the last Masterscope question. For 
| example, following the command WHO IS USED FREELY ВУ 
PARSE, the user could ask WHO BINDS THOSE to find out where 
those variables are bound. 
ON PATH pathoptions “| Refers to the set of functions which would be printed by the 
| соттапа 5НОМ РАТН5 pathop tions. For example, IS Ғ00 
BOUND BY ANY ON PATH TO 'PARSE tests if FOO might be 
bound "above" the function PARSE. pathoptions are explained in 
detail on page 20.15. 
Determiners 
Set phrases may be preceded by a determiner. A determiner is one of the words THE, АМУ, WHO > 
or WHICH. The "question" determiners (WHO and WHICH) are only meaningful in some of the | 
commands, namely those that take the form of questions. ANY and WHO (or WHOM) can be used 
alone; they are "wild-card" elements, e.g., the command WHO USES ANY FREELY, will print out 
the names of all (known) functions which use any variable freely. If the determiner is omitted, ANY _ 
is assumed; e.g. the command WHO CALLS ‘(PRINT PRIN1 PRINZ) will print the list of | 
_ functions which сай any of print, print, prin2. THE is also allowed, e.g. WHO USES THE RECORD | 
FIELD FIELDX. 2 4% 
Types 


А set phrase may also have a type; that is, а set may contain either functions, variables, files, record | | 
names, record field names or property names. The type is used by мше оре in a variety of тыа 
when interpreting the set phrase: | 


(1) Set types are used to disambiguate possible parsings. For example, both commands WHO 
SETS ANY BOUND IN X OR USED BY Y and WHO SETS ANY BOUND IN X OR 
CALLED BY Y have the same general form. However, the first case is parsed as WHO SETS - 
ANY (BOUND BY X OR USED BY Y) since both BOUND BY X and USED BY Y refer to _ 
variables; while the second case as WHO SETS ANY BOUND IN (X OR CALLED BY Y). 
since CALLED BY Y and X must refer to functions.? | 


(2) The type is used to determine the modifier for USE: FOO USES WHICH RECORDS is 
A equivalent to FOO USES WHO AS A RECORD FIELD. | 


(3) The interpretation of CONTAIN depends on the type of its object: the command WHAT 


FUNCTIONS ARE CONTAINED IN MYFILE prints the list of functions in a WHAT 
RECORDS ARE ON MYFILE prints the list of records. 


Note that parentheses may be used to group phrases. 
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(4) Тһе implicit "universe" in which а set expression is interpreted depends on the type: ANY 
VARIABLES @ GETD is interpreted as the set of all variables which have been noticed by 
Masterscope (е. bound or used in any function which has been analyzed) that also have a 
definition. ANY FUNCTIONS @ (NEQ (GETTOPVAL X) 'NOBIND) is interpreted as the set 
of all functions which have been noticed (either analyzed or called by a function which has 
been analyzed) that also have a top-level value. 


The type may ђе determined by the context within the command (eg, in 
CALLED BY ANY ON FOO, the set ANY ON FOO is interpreted as meaning the functions on FOO 
since only functions can be CALLED), or the type may be given explicitly by the user (eg., 
FUNCTIONS ON ЕТЕ). The following types are recognized: FUNCTIONS, VARIABLES, FILES, 
PROPERTY NAMES, RECORDS, FIELDS, 1.5.0Р85.20 


CONJUNCTIONS 


Sets may be joined by the conjunctions AND and OR or preceded by NOT to form new sets. AND is 
always interpreted as meaning "intersection"; OR as "union", while NOT means "complement". For 
example, the set CALLING X AND NOT CALLED BY Y specifies the set of all functions which call 
the function X but are not called by Y. | 


Masterscope's interpretation of AND "T OR follow LISP conventions rather than the conventional 
English interpretation. For example "calling X and Y". would, in English, be interpreted as the 
intersection of (CALLING X) and (CALLING Y); but Masterscope interprets CALLING X AND 
Y as CALLING ('X AND 'Y); which is the null set. Only sets may be joined with conjunctions: 


joining modifiers, as in USING X AS A RECORD FIELD OR PROPERTY NAME, is not allowed; | 


in this case the user must say USING X AS A RECORD © FIELD OR. USING X AS A 
PROPERTY NAME 


As described above, the type of sets is used to disambiguate parsings. The algorithm used is to first 
try to match the type of the phrases being joined and then try to join with the longest preceding 


phrase. In any case, the user may group phrases with parentheses to specify the manner in which 
conjunctions should be parsed. 


COMMANDS 


The normal mode of communication with Masterscope is via "commands". These are sentences in 


the Masterscope command language which direct Masterscope to answer questions or ЫШ 


various operations. The syntax of Masterscope commands 15 described below: ead 


ANALYZE set Analyze the functions in set (and any ee called by them) aud | 


include the information gathered i in the database. 


10 or abbreviations FNS, VARS, PROPNAMES or the singular forms FUNCTION, FN, VARIABLE, VAR, FILE, 
PROPNAME, RECORD, FIELD. Note that most of these types correspond to builtin "file package types". (See 
Section 14). | 


11 


Masterscope will not re-analyzing a function if it thinks it already has valid information about that function in its 
database. The user may use the command REANALYZE sct to force re-analysis. For example, this would be necessary 
if the user had disabled or subverted the file package, e.g. performed putd's to change the definition of functions, 
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A Note that whenever a function is referred to in a command as a "subject" of one of the relations, 
it is automatically analyzed; the user need not give an explicit ANALYZE command. Thus, WHO IN 
MYFNS CALLS FIE will automatically analyze the functions in MYFNS if they have not already 


+ к + + 


++ 


been analyzed. 


Note also that only expr definitions will be analyzed; that is, Masterscope will not analyze 
compiled code. If there is no in-core definition for a function (either in the de inition cell or an 
EXPR property), Masterscope will attempt to read in the definition from a Пей? If necessary, the 
definition will be dwimifyed before analysis. 


ERASE set 


SHOW PATHS pathoptions 


set relation set 
set 15 |АЌЕ set 
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Erase all information about the functions in set from the database. 
ERASE by itself clears the entire database. 


Displays a tree of function calls. pathóptions are destribed c on -page 
20.15. 


This command has the same format as an English sentence with a 
subject (the first set), a verb (the relation or IS or ARE), and an 
object (the second set). Any of the sets within the command may 
be preceded by the question determiners WHICH or WHO (or just - 
WHO alone). For example, WHICH FUNCTIONS CALL X prints the 
list of functions that call the function X. relation may be one of the 
relation words in present tense (CALL, BIND, TEST, SMASH 
etc.) or used as а passive (e.g. WHO IS CALLED BY мно). АР 


Тһе interpretation of the command depends on the number of | 
question elements present: 


(1)  Ifthere is no question element, the command is treated as ап 
assertion and Masterscope returns either T or NIL, 
depending on whether that assertion is true. Thus, ANY IN 
MYFNS CALL HELP will print T if any function in MYFNS . 
call the function help, and NIL otherwise. 


(2) If there is one question element, Masterscope returns the list. 


of items for which the assertion would be true. For example > 


MYFN BINDS WHO USED FREELY BY YOURFN prints the 
list of variables bound by MYFN which are also used freely 
by YOURFN. 


(3 If there are two question elements, Masterscope will print a 
doubly indexed list: 


=. WHO CALLS WHO IN /FNS2 


Files which have becn explicitly mentioned previously in some command are searched first. If the definition cannot 


be found on any of those files, Masterscope looks among the files on filelst for a definition. If a function is found in | 
this manner, Masterscope will print a message "(reading from filename)". If no definition can be found at all, 
Masterscope will print a message "fn can't be analyzed". If the function previously was known, the message 


"fn disappeared!" is printed... 


B Other variants are allowed, e.g. WHO DOES X CALL, IS FOO CALLED BY ЕТЕ, etc, 
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RECORDSTATEMENT -- /RPLNODE | | 
RECORDECL1 -- /NCONC, /RPLACD, /RPLNODE 
RECREDECLARE1 -- /PUTHASH 

UNCLISPTRAN -- /PUTHASH, /RPLNODE2 
RECORDWORD -- / RPLACA 

RECORD1 -- /RPLACA, /SETTOPVAL 
EDITREC -- | / SETTOPVAL | 


EDIT WHERE set relation set [- editcoms] 


SHOW WHERE set relation set 


EDIT set [- editcoms] 


DESCRIBE set 


CHECK set 
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(WHERE тау be omitted.) The first set refers to a set of functions. 
The EDIT command calls the editor on each expression where the 


relation actually оссиг5.1“ For example, EDIT WHERE ANY CALL 


ERROR will call editf on each (analyzed) function which calls error 
stopping within a TTY: at each call to error. editcoms, if given, are 
a list of commands passed to editf to be performed at each 
expression. For example, EDIT WHERE АМҮ 
CALLS MYFN DIRECTLY - (SW 2 3) P will switch the first 
and second arguments to MYFN in every call to MYFN and print the 
result. EDIT WHERE ANY ОМ MYFILE CALL ANY NOT @ GETD 
will call the editor on any expression involving a call to an 
undefined function. Note that EDIT WHERE X SETS Y will point 
only at those expressions where Y is actually set, and will skip over 
places where Y is otherwise mentioned. 


Like the EDIT command except merely prints out the expressions 


without calling the editor. 


calls editf on each function in set. editcoms, if given, will be passed 
as a list of editor commands to be executed. For example EDIT 
ANY CALLING ЕМ1 - (R FN1 FN2) will replace FN1 by FN2 in 
those functions that call FN1. 


Prints out the BIND, USE FREELY and CALL information about 
the functions in set. For example, the command | DESCRIBE 
PRINTARGS might print out: 


PRINTARGS[N; FLG] 
binds : TEM,LST, X 
calls : MSRECORDFILE, SPACES, PRIN1 
called by: PRINTSENTENCE ,MSHELP, CHECKER 


showing that printargs has two arguments, п and Пр, binds 
internally the variables tem, Ist and x, calls msrecordfile, spaces and 
prinl and is called by printsentence, mshelp, and checker. 


checks for various anomolous conditions (mainly in the compiler 
declarations) for the files in set (if set is not given, filelst is used). 
For example, this command will warn about variables which are 


Currently one cannot EDIT WHERE a file CONTAINS a datum, nor where one function CALLS another SOMEHOW. _ 
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FOR variable set i.s.tail 


HELP 
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bound but never referenced, functions in BLOCKS delarations which 
aren’t on the file containing the declaration, variables declared as 
LOCALFREEVARS but which are used freely in contexts where they 
are not bound, functions declared as ENTRIES but not in the 
block, variables which may not need to be SPECVARS because they 
are not used freely below the places where they are bound, etc. 


This command provides a way of combining CLISP iterative 
statements with Masterscope. An iterative statement will be. 
constructed in which var is iteratively assigned to cach element of 
set, and then the iterative statement tail i.s.tail is executed. For 
example, FOR X CALLED BY FOO WHEN CCODEP DO (PRINT 
(ARGLIST X)) will print out the argument list of all of the | 
compiled functions which are called by FOO. 


Prints out the summary of Masterscope command syntax as shown 
on the next page. Optional elements are shown in brackets ГТ; 
alternatives are separated with vertical bars | or are listed on 
separate lines; words in angle brackets <> аге "тега-објес 5"; other 


| е words аге "noise words" and may be omitted. 


Note: any Же тау be followed by OUTPUT fi lename to send output to the given fi le rather 
than the terminal, eg. WHO CALLS WHO OUTPUT CROSSREF. 


This completes the presentation of the Masterscope command language. 
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|а «command? is: 


| [RE ]ANALYZE <functions> 

| ERASE «functions? 

| show PATHS <pathoptions> 

| <set> {<relation>!lIS!ARE} <set> 

| EDIT where <functions> [<relation> <set>] Г - <edit соттапа5> ] 
| SHOW where «functions? «relation»? «set» 

| CHECK «files» m | 

| FOR «variable»? «set» <1.5. орг? «expression? 


то о ы» ae T мо од оқы ота во ow ме оп мо се мо aD ош мо ow мо от и еко ош ом «и om am Чт aw ow ЧО ow Sw ша да 590 ом от ма е пе хо х х х х х х х пар оо ес то е Jill ма мо 


ја <set> is (at least опе of): 


|а determiner + а type + a specification 

| 

| ТНЕ FUNCTIONS | Г" ЈСабот 1151} 

| АМУ VARIABLES @ <pred> | 

| МНІСН PROPERTY NAMES IN <expression> 

| WHO RECORDS <relation>ING «set» 

| | FIELDS = «гета Топ 0 {BY!IN} <set> 
| FILES THAT <relation> <set> 
| LIKE <edit-pattern> 

| ON <files> 

| FIELDS ОҒ <records> 

| <blockword> {ON <files>!0F «functions?) 

| 


<functions>, <files>, etc. аге <set>s whose type is implied. 


- иа ааа но a a a шш ш a чш чш чш чо ee ewe wwe we = чш ош = cm <= че "ш че око eee = = = 


а <relation> is а verb and optional modifier: 


| 

| verbs: | modifiers (anywhere after the ТТ 

| CALL ао SOMEHOW | FOR РЕНО VALUE 

| BIND 

| USE is AS a {RECORD! PROPERTY | record іе пате 

| USE пер AS а CLISP word 

| USE — FREELY!LOCALLY 

| SET ech FREELY!LOCALLY 

| SMASH — FREELY LOCALLY 

| TEST e FREELY!LOCALLY 

| REFERENCE 2%% FREELY!LOCALLY 

| FETCH 

| REPLACE SoS eS Peer ese SSS aS оно а еа ce SS Seen ee 

| CREATE | <blockword>: ENTRIES, GLOBALVARS, FREEVARS, 

| CONTAIN | SPECVARS, LOCALFREEVARS, BLKFNS or BLOCKFNS - 
«pathoptions»: abbreviations & synonyms: 


| | 

| FROM «functions? | FNS = FUNCTIONS PROPS = PROPERTIES 
| ТО <functions> | VARS = VARIABLES | 

| AVOIDING <functions> | (& singular FN, VARIABLE, etc) 

| NOTRACE <functions> | FREE = FREELY LOCAL = LOCALLY 

| SEPARATE <functions> | AMONG = AVOIDING NOT 

|  LINELENGTH «number? | 

| <sets> may be joined by AND or OR or preceded by NOT. 
| Any command can be followed by OUTPUT остало 
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20.1.2 PATHS 


In trying to work with large programs, the user can lose track of the hierarchy which defines his 


J program structure. Masterscope can aid the user by providing a map showing the calling structure 
Of a set of functions, via the SHOW PATHS command. The SHOW PATHS command prints out a 


tree structure showing which functions call which other functions. For example, the command 
SHOW SERIES FROM MSPARSE will print out the structure of Masterscope’s parser: 


T; MSPARSE MSINIT MSMARKINVALID 
2. MSINITH MSINITH 
oe.  MSINTERPRET MSRECORDFILE 
4, | MSPRINTWORDS 
“ 5, | PARSECOMMAND GETNEXTWORD CHECKADV 
6. | | PARSERELATION {a} 
7. | | . PARSESET (b) ; 
8. | | PARSEOPTIONS {c} 
9. | | MERGECONJ GETNEXTWORD (5) 
10. | GETNEXTWORD {5} 
11: | FIXUPTYPES SUBJTYPE 
12. | | ОВЈТУРЕ 
k | | | FIXUPCONJUNCTIONS MERGECONJ (9) 
14. | | MATCHSCORE 
15. MSPRINTSENTENCE | 
---------------------------------------------- -------- overflow - а 
16.PARSERELATION GETNEXTWORD (5) | 
17. | СНЕСКАРУ гумите 
sec puer соната QE Ie S NU GM RN I MM overflow - b 
19.PARSESET PARSESET 
20. GETNEXTWORD (5) 
21. PARSERELATION (6) 
22. |J A SUBPARSE GETNEXTWORD (5) 
Meum ышы дыы SS SSS ерик meu шиа кышы ашакы тике EE overflow - с. 
23.PARSEOPTIONS GETNEXTWORD {5} | 
24.  PARSESET (19) 
Figure 20-3 


Figure 20-3 displays that the function msparse calls теши, msinterpret, and msprintsentence. - 
msinterpret in turn calls msrecordfile, msprintwords, parsccommand, getnextword, fixuptypes, and _ 
fixupconjunctions. The numbers in braces () afler a function name are backward references: they | 
indicate that the tree for that function was expanded оп а previous line. The lowercase letters in 
braces are forward references: they indicate that the tree for that function will be expanded below, _ 


Since there is no more room on the line. The vertical bar is used to keep the output aligned. 
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Paths in Masterscope 


The SHOW PATHS command takes the omm: SHOW PATHS followed by some combination of the. 


. following path options: 
FROM set 


TO set 


Display the function calls from the elements of set. 


Display the function calls leading го elements of set. If TO is given | 
before FROM (or no FROM is given), the tree is "inverted" and a 
message, (inverted tree) is printed to warn the user that if 
FN1 appears after FN2 it is because F N1 is called by FN2. 


When both FROM and TO are given, the first one indicates а set of functions which are to be 
displayed while the second restricts the paths that will be traced; i.e., the command SHOW PATHS 
FROM X TO Y will trace the elements of the set CALLED SOMEHOW BY X AND CALLING Y 


SOMEHOW. 


If TO is not given, TO KNOWN OR NOT @ GETD is assumed: that 15, oniy functions which have 
been analyzed or which are undefined will be included. | 


AVOIDING set 


NOTRACE set 


SEPARATE set 


LINELENGTH n 


15 


Do not display any function in- T AMONG is recognized as a 
synonym for AVOIDING NOT. For example, SHOW PATHS TO 
ERROR AVOIDING ON FILE? will not display (or trace) any 
function on FILE2. 


Do not trace from any element of set NOTRACE differs from 
AVOIDING in that a function which is marked NOTRACE will be 
printed, but the tree beyond it will not be expanded; tbe functions 
in an AVOIDING set will not be printed at all. For example, SHOW 
PATHS FROM ANY ON FILE1 NOTRACE ОМ FILE2 will display 
the tree of calls eminating from FILE1, but will not expand any 
function on FILE2. 


Give each element of set a separate tree. Note that FROM and TO 
only insure that the designated functions will be displayed. 
SEPARATE. can be used to guarantee that certain functions will 
begin new tree structures. SEPARATE functions are displayed in the 
same manner as overflow lines; ie, when one of the functions 
indicated by SEPARATE is found, it is printed followed by a 
forward reference (a lower-case letter in braces) and the tree for 
that function is then expanded below. 5 Ж 


Resets linelength to n before displaying the tree. The linelength is 
used to determine when a part of the tree should "overflow" and 
be expanded lower. 


Note that Masterscope will analyze a function while printing out the tree if that function has not previously been 


seen and it currently has an expr definition; thus, any function which сап be analyzed will be displayed. | 


2015. 
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20.1.3 AFFECTING MASTERSCOPE ANALYSIS 


Masterscope will analyze the expr definitions of functions and note in its database the relations that 


_ function has with other functions and with variables. То perform this analysis,  Masterscope. uses 
. templates which describe the behavior of functions. 


А template is a pattern of a function’ 5 evaluation. A template 15 а list structure containing апу of | | 


Ше ота atoms: 


PPE 


ми 


+ 


+ + 


+ 


SET | 
SMASH 


TEST 
PROP 
FUNCTION 


EVAL | 


RETURN 


EFFECT. 


FETCH 


example, | the 


Ifan expression appears in this location, there is most likely а parenthesis 
еггог. 


Тһе expression occuring at this location is not evaluated. For example, the 


template for QUOTE is (NIL . PPE). 


^A variable appearing at this place is set. E.g., the template for SETQQ is 


(SET NIL . PPE). 


The value of this expression is smashed. For example, the с template for 
DREVERSE is (SMASH . PPE). 


This expression is used as a predicate (that is, the only use of the value of 
the expression is whether it is NIL or non-NIL.) For example, the 
template for NULL is (TEST . PPE). | 


The value of this expression is used as a property name. If the expression | 
is of the form (QUOTE atom), Masterscope will note that atom is USED 
AS A PROPERTY NAME. For example, the арш for getprop is VEN 
PROP . PPE). © 


The expression at this point is used as a functional argument. For 
template for MAPC is 
(SMASH FUNCTION FUNCTION . PPE). Y 


The expression at this location is evaluated (but not set, smashed, tested, 


used as a functional argument, etc.). 


The value of the function e which this is the template) is the value of 
this expression. 


Тһе expression at this location is evaluated, but the value is not used. For 
example, the template for PROGN is (.. 


EFFECT RETURN). 


An atom at this location is а field which is fetched. 


16 Masterscope notes this as а "call" to the function "ppe" daai. Note that, when Masterscope finds a possible 
parenthesis error in the course of analyzing a function definition, rather than printing the usual "и prints outa _ 


"7" instead. 


17 


Actually, Masterscope distinguishes between functional arguments to. functions which " ‘compile open" from those that 


do not. For the latter (e.g. SORT and пазе! {һе (океп їп the template is Е UNCTIONAL rather than FUNCTION. 
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КЕРІ АСЕ 
. RECORD 
CREATE 
BIND 
CALL 


CLISP 
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An atom at this location is a field which is replaced. 
An atom at this location is used as a record name. 

An atom at this location is a record which is created. - 
An atom at this location is a variable which is bound. | 
An atom at this location is a function which is called 


An atom at this location is used as a clisp word. 


In addition to the above atoms which occur in templates, there are some “special forms" which are 


lists keyed by their car. 


. template 


(BOTH template template) 


Any part of a template may be preceded by the atom .. (two periods) 


which specifies that the template should be repeated an indefinite number 
(п> 0) of times to fill out the expression. For example, the template for 
COND might be (.. (TEST .. EFFECT RETURN)) while the template 
(ог SELECTQ is (EVAL .. (NIL .. EFFECT RETURN) RETURN). 


analyze the current prea twice, using the each of the сна іп 
turn. | 


(IF expression template template) _ 


evaluate expression at analysis time (the variable EXPR will be bound to 
_ the expression which corresponds to the IF), and if the result is non-NIL, 


use the first template, otherwise the second. ТЕ expression is a literal 


atom, it is applyd to EXPR. For example, (IF LISTP (RECORD 


FETCH) FETCH) specifies that if the current expression is a list, then the 
first element is a record name and. the second element a field name, 
otherwise it is a field name. 


(8 exprform templateform) 


(MACRO . macro) 


evaluate exprform giving e хрг, evaluate КЕЛЕР giving template. 
Then analyze expr with template. @ lets the user compute on the fly 


both a template and an expression to analyze it with. The forms can use 
the variable EXPR, which is bound to the current expression. 


macro is interpreted in the same way as a compiler macro (see Section 18) 
and the resulting form is analyzed. 1 | 


Some examples of templates: 


18 


Additionally, the template for a function may be the atom MACRO itself, in which case, Masterscope will use the 


MACRO property of the function itself. This is useful when analyzing code which contains calls to user-defined 
compiler macros. If the user changes a macro property (e.g. by editing it) of an atom which has template = MACRO, 
Masterscope will mark any function which uscd that macro as needing to be reanalyzed. 
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function | | | . template 
AND | | (TEST .. RETURN) | 
MAPCAR | (EVAL FUNCTION FUNCTION) Е 


Templates тау be changed and new templates defined via the function: 


- gettemplateffn] returns current template of fn. 


settemplate[fn; template] Changes the template for the function fn and returns the old value. 
| If any functions in the database are marked as calling fn fn, Hey will 
be marked as needing re-analysis. | | 


20.1.4 DATA BASE UPDATING 


Masterscope is interfaced to the editor and file package so that it notes whenever a function has 

been changed, either through editing or loading іп a new definition. Whenever a command is given - 
which requires knowing the information about a specific function, if that function has been noted 
as being changed, the function is automatically re-analyzed before the command is interpreted. If 


. the command requires that all the information in the database be consistent (e.g., the user asks WHO 


CALLS X) then all functions which have been marked as changed are re-analyzed. | 


20.1.5 MASTERSCOPE ENTRIES 


calls[fn;usedatabase] · . fn can be a function name, a definition, or a form. calls will also . 
work on compiled code. calls returns a list of four elements: a list of 
all the functions called by by fn, 19 a list of all the variables bound in 
fn, a list of all the variables used freely in fn, and a list of the 
variables used globally in fn. For the purpose of calls, variables 
used freely which are on globalvars or have a property GLOBALVAR 

value T are considered to be used globally. If usedatabase is NIL 
(or fn is not a litatom), calls will perform a one-time analysis of fn. 
Otherwise (i.e. if usedatabase is non-NIL and fn a function пате), 
calls will use the information in Masterscope's database (fn will be 
analyzed first if necessary). | 


callsccode[fn] The sub-function of calls which analyzes compiled. code. callsccode 
returns a list of five elements: a list of all the functions called via 
"linked" function calls, a list of all functions called regularly, a list - 


Functions called via "linked" calls from compiled PTT are indicated by semicolons packed around their name; eg. 
call[MASTERSCOPE] might return ((;MASTERSCOPEXEC; ;MSINTERPRET; ;PRINT; HELP) --). This 
feature can be suppressed by setting nopackcallsflg to T. | 
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freevars[fn;usedatabase] 


masterscope[command] 


Masterscope 


of variables bound in fn, a list of variables used freely, and a list of 
variables used globally. 


Equivalent to caddrfcalls[fn;usedatabase]]. Returns the ЊЕ of |. 
variables used freely within fn. | | 


Top level entry to Masterscope. If command is NIL, will enter into- 
a userexec in which the user may enter commands. If command is 
not NIL, the command is interpreted and masterscope will return | 
the value that would be printed by the command. Note that only do 
the question commands return meaningful values. 


setsynonym[newphrase;meaning] 


Defines a new synonym for ТЕТЕ 5 parser. Both newphrase 
and meaning are lists of words; anywhere newphrase is seen in a 
command, meaning will be substituted. For example, 
setsynonym|GLOBALS ; (VARS IN GLOBALVARS OR @(GETPROP | 
X 'GLOBALVAR) ) )] would allow the user to refer. with the single 
word GLOBALS to the set of variables which are either in globalvars — 
or have a GLOBALVAR property. 


The following functions are provided for users who wish to write their own routines using . 


Masterscope's database: 


parserelation[relation] 


relation is a relation phrase; e.g. parserelation[(USE FREELY)]. 
parserelation returns an internal representation for relation. For use 
in conjunction with getrelation. 


getrelation[item;relation;inverted] 


relation is an internal representation as returned by parserelation (if 
not, getrelation will first perform parserelation{relation]); item is an 
atom. getrelation returns the list of all atoms which have the given 
relation to item. For example, getrelation[X;(USE FREELY)] 
returns the list of variables that X uses freely. If inverted is T, the - 
inverse relation is used; e.g. getrelation[X; (USE FREELY) ;T] 
returns the list of functions which use X freely. 


If item is NIL, getrelation will return the list of atoms which. have 


relation with any other item; ie. answers the question WHO- 
relationS ANY. Note that getrelation does not check to see if item 
has been analyzed, or that other functions that have been changed 
have been re-analyzed. 


testrelation[item;relation;item2;inverted] 


equivalent to memb[item2;getrelation[item; relation: inverted], that i is, 

tests if item and item2 are related via relation. If item2 is NIL, the 

call is equivalent to not[null[getrclation[item;rcelation;inverted]]], i.e., 

testrelation tests if item has the given relation with any other item. 
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maprelation[relation;map fn] Calls the function m apfn on every pair of items related via relation. 
| © Jf nargs s[mapfn] is 1, then mapfn is called on every item which has 
the given relation to any other item. 


updatefn[fn;evenifvalid] ^ 1 Equivalent to the command ANALYZE "ѓа: that is, updatefn will 
| analyze fn if fn has not been analyzed before or if it has been. 
changed since the time it was analyzed. If evenifvalid is set, 
updatefn will re-analyze fn fn even if Masterscope thinks it has a valid 
analysis in the database. 


updatechanged[] - Performs updatefo[fn] on every function which has been marked as 
| | changed. | 
msmarkchangedffa] | Mark that fn has been changed and needs to be reanalyzed. 
dump database[fnlst]} Dumps the current M asterscope database on the current output file - | 


іп а loadable form. If fnlst is not NIL, dumpdatabase will only | 
dump the information for the list of functions in 8115.20 The 
variable databasecoms is initialized to ((E (DUMPDATABASE ) )); 
thus, the user may merely perform makefile[DATABASE . extention] 
to save the current Masterscope database. If a Masterscope database | 
already exists when a DATABASE file is loaded, the database on the- 
file will be merged with the one in соге,21 


20.1.6 ERROR MESSAGES 


When the user gives Masterscope a command, the command is first parsed, i.e. translated to an . 
internal representation, and then the internal representation is interpreted. If a command cannot be 
parsed, eg. if the user typed SHOW WHERE CALLED BY X, the message 
"Sorry, I can't parse that!" is printed and an error is generated. If the command is of 
the correct form but cannot be interpreted (e.g. the command EDIT WHERE ANY CONTAINS 
ANY) Masterscope will print the message "Sorry, that isn't implemented!" and generate. 
an error. If the command requires that some functions having been analyzed (e.g., the command | 
WHO CALLS X) and the database is empty, Masterscope will print the message | 


. "Sorry, no functions have been analyzed!" and generate an error. 
y | | BS 


20.1.7 NOTICING CHANGES THAT REQUIRE RECOMPILING 


When a record declaration, iterative statement operator or compiler macro is changed, and 


20 — The databasefns package (section 24) provides a more convenient way of saving data bases along with the source files 


which they correspond to. 
21 Note that functions whose definitions are different from their definition when the database was made must be | 
REANALYZEd if their new definitions are to be noticed, | 
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Masterscope has "noticed" a use of that declaration or macro (ie. it is used by some function 
known about in the data base) Masterscope will alert the user about those functions which might 
need to Бе re-compiled (e.g. they do not currently have expr definitions). The functions which 
need recompiling are added to the list needunsave and a message is printed out: The functions 


fnl, fn2,.. use compiler macros which have changed. Call UNSAVEFNS() to load 


and/or unsave them. The function: 


unsavefns[] Uses loadfns or unsavedef to make sure that all functions in the list 
needunsave have expr definitions, and then sets needunsave to NIL. 


20.1.8 IMPLEMENTATION NOTES 


Masterscope keeps a database of the relations noticed when functions are analyzed. The relations 
are intersected to form "primitive relationships" such that there is little or no overlap of any of the 
primitives. For example, the relation SET is stored as the union of SET LOCAL and SET FREE. 


The BIND relation is divided into BIND AS ARG, BIND AND NOT USE, and SET LOCAL, SMASH 


LOCAL, etc. Splitting the relations in this manner reduces the size of the database considerably, to 
the point where it is reasonable to maintain a Masterscope database for a large system of а 
during а normal debugging session. | 


Еасһ primitive relationship is stored in a pair of hash-tables, one for the "forward" direction and. | 


one for the "reverse". For example, there are two hash tables, USE AS PROPERTY and USED AS 
PROPERTY. To retrieve the information from the database, Masterscope performs unions of the 


hash-values. For example, to answer FOO BINDS WHO Masterscope. will look in all of the tables 


which make up the BIND relation. The "internal representation" returned by parserelation is just a 
list of dotted pairs of hash-tables. To perform getrelation requires only mapping down that list, 
doing gethash’s on the appropriate hash- tables and unioning the result. 


Hash tables are used for a variety of reasons: storage space is smaller; it is not necessary to 
maintain separate lists of which functions have been analyzed (a special table, DOESN'T DO 
ANYTHING is maintained for functions which neither call other functions nor bind or use any 


с variables); and accessing is relatively fast. Within any of the tables, if the hash-value would be a list - 
of one atom, then the atom itself, rather than the list, is stored as the hash-value. This also reduces 


the size of the database significantly. 


This completes the section on Masierscope: 
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Extra functions may be noticed; for example if FOO contains a (f etch (REC X) --), and some declaration other 
than REC which contains an X is changed, Masterscope will still think that FOO needs to be loaded/unsaved. | 
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20.2 HELPSYS?. 


Helpsys provides yet another form of on-line assistance to the user, namely in the area of 


= documentation of Interlisp. Helpsys uses the Interlisp Reference Manual as а data base, апа 
answers simple questions about Interlisp by presenting the appropriate passages from the manual. 
Inquiries are made in the form of simple sentences, void of punctuation, terminated with a 


carriage-return. The она. ample session illustrates the use of Helpsys. User пр аге 
underlined. | | | | 


-HELPSYS() 


Туре ??? «CR»? for assistance 


ITELL ME ABOUT EVAL? 


Subcategories available: 


1. function description 
2. break command 


3. cross referenced subject 


4. ERRORSET (cross referenced әйнек PE 
Which one ? FUNCTION DESCRIPTION ` (0 user typed То 


8 
eval[x] | | eval evaluates the expression x and returns this  - 
| value i.e., eval provides а way of oe the — 
| interpreter. 
8 Oo 


In . INTERLISP-10, eval 15 а  зиђг so that the "name" | Хх does not 
actually appear on the stack. | | Б и За 


| Note that eval is itself а lambda ; 
type fineeton, $0 its argument 15 first 
evaluated, e.g., | | | 


+SET(FOO (А001 3)) 
(ADD1 3 

«(EVAL FOO) 

ў 


_ СЕМА (Е00) ог "(ЕМА (QUOTE F00)) 
(ADD1 3) 


| REDO2 

Subcategories available: 

1. function description 

2. break command 

3. cross referenced subject 

4. ERRORSET {cross referenced subject} 

Which one 7 BREAK COMMAND fuser typed 22% 


EVAL | Same as GO or OK except that the break is 


23 Helpsys was written by R. L. Walker II, 
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maintained after the evaluation. The user can 
then interrogate the value of the break which is 
bound on the variable !value, and continue with 
the break. Typing GO or OK following EVAL will 
not cause reevaluation but another EVAL will. 
EVAL is а useful command when the user 15 not 
sure whether or not the break will produce the | 
correct value and wishes to be able to do 
something about it if it is wrong. | 


m 
> 
о 
c 
и 
a 


I TELL 


cs illl d 


— 


(UB as a break command from section 15) „падат = 
| | UB unbreaks brkfn, е.д., 


(FOO BROKEN) 
: UB 


Valid arguments for BREAK1 are: [BRKEXP ; BRKWHEN ; BRKFN ; BRKCOMS ; BRKTYPE ] 


ITELL ME ABOUT THE LAST ARUGMENT OF BREAK1» - 

-ARGUMENT 

Subcategories available: 

function description 

topic description 

cross referenced subject 

TRACE (cross referenced subject) 

FAULTEVAL (cross referenced subject) 

HELP (cross referenced subject) 

Which one ? FUNCTION DESCRIPTION fuser typed 127 

breaki1[brkexp;brkwhen;brkfn;brkcoms; brktype] | 

is an nlambda. brktype is NIL for 

user breaks, INTERRUPT for control-H breaks, and 
ERRORX for error breaks. | 


St ee го» 


[TELL ME ABOUT THE 2ND ARG OF CHANGEPROP2 


(CHANGEPROP as a function description from section 7) 

changeprop[x;propi;prop?2] | | 
Changes name of property ргор to ргор2 on. 
property list of x, (but does not affect the 
value of the property). | 


{TELL ME ABOUT ERROR ІМ ARRAYSIZE 
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(ARRAYSIZE as a function description from section 1) 


а 


Generates ап 


еггог, АВб МОТ ARRAY, if а is not an array. 


| МНАТ IS THE VALUE OF МАРС2 


во шиши Ен и ани иа cnc оа 


(МАРС as а function description from section 11) 


тарс[тарх; mapfni;mapfn2] 


| ТЕЦ. ME ABOUT SPLICE? 


The value of mapc is NIL. . mapc compiles open. 


(SPLICE, type of read-macro, from section 14) 


(2) SPLICE 


The result (which should be а list or NIL) is 
nconc'ed into the input list, e.g., if ! is 
defined by (SPLICE (LAMBDA NIL (APPEND F00))), 
and the value of foo is (A B C), when the user 
inputs (X 1 Y), the result will be a ABC Y). 


[TELL МЕ ABOUT CLISPSFLG2 


1. CLISPFLG 

2. CLISPIFTRANFLG 

3. CLISPIFYENGLSHFLG 
4. CLISPIFYPACKFLG 
5. CLISPIFYPRETTYFLG 


6. CLISPRETRANFLG 


Which one ? CLISPIFYPRETTYFLG {user typed 59 


Subcategories available: 


1. prettydef variable/parameter 
2. CLISP variable/parameter | 
Which опе ? CLISP VARIABLE/PARAMETER fuser typed 2997 


clispifyprettyflg 


if non-NIL, causes prettyprint їо CLISPIFY 
selected function definitions before printing . 
them according to the following interpretations 

| 131 | 


of clispifyprettyflg: 


Another way to inform prettyprint to clispify functions is for the 


function to have a CLISP declaration containing the мога CLISPIFY.. 


ALL all functions | 


T, EXPRS functions currently defined as 
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exprs 


CHANGES functions marked as having 
been changed 


a list a member of that list 


clispifyprettyflg is (temporarily) reset toT 
when makefile is called with the option 
CLISPIFY, and reset to CHANGES when the file 
being dumped has the property FILETYPE value 
CLISP. clispifyprettyflg is initially NIL. 


If clispifyprettyflg is non-NIL, and the only” transformation 
performed by DWIM are well formed CLISP transformations,  i.e., no 
spelling corrections, the function will not be marked as changed, 
since it would only have to be re-clispified and re-prettyprinted 
when the file was written out. | 254 


=coroutines% and% generators 


 (coroutines and generators as a cross referenced subject from section 
12) | 


5 
12.7 Coroutines and Generators 


Designed and implemented by D.G. Bobrow, who also did the 
documentation. Early versions of the Соппіуег possibilites-list 
package were written by Henry Thompson. Daryle Lewis found and 
corrected a number of bugs, and wrote the compiler macros that до 
with the package. 


This section describes an application of the spaghetti stack facility to 
provide mechanisms for creating and using simple generators (with and 
without CLISP, Section 23), generalized coroutines, and Conniver style 
possibility lists. | 


I MORE? 


coroutines and generators ...continued from section 12 


A generator 15 like а subroutine except that it retains information 
about previous times it has been called. Some of this state may be data 
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(Тог example, the seed іп а random number generator), and some тау be in 


program state (as іп a recursive generator which finds all the atoms in 


a list structure). For example, if listgen is defined using defineq as: 


(LISTGEN (L) 00 | 
(ТЕ L THEN (PRODUCE 1:1) (LISTGEN L::1))) 


we can use the function generator (described below) to create a 
generator that uses listgen to produce the elements of a list one at a 
time, e.g., | 

. GRe(GENERATOR (LISTGEN "(А B C)) 


creates a generator, which can be called by 


(GENERATE GR) 


to produce as values оп successive calls, А, В, С. When generate (not 


generator) is called the first time, 1% simply starts evaluating 
(LISTGEN "(АВ C)). produce gets called from listgen, and pops back up 
to generate with the indicated value after saving the state. When 
generate gets called again, it continues from where the last produce 


left off. This process continues until finally listgen completes and 


12.15 
More ? No 


тока 
= thank-you 
м | 
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SECTION 21 
MISCELLANEOUS! 


21.1 MEASURING FUNCTIONS 


time[timex ;timen;timetyp] 


is an nlambda function. It executes the computation timex, and 
prints out the number of conses and computation time. ‚ Garbage | 
collection time is subtracted out. 


*TIME((LOAD (QUOTE PRETTY) (QUOTE PROP] 
FILE CREATED 1-AUG-78 14:56:12 
PRETTYCOMS 

collecting lists 

582, 10291 free cells 

13169 CONSES 

29.484 SECONDS 

PRETTY 


If timen is greater than 1 (timen=NIL equivalent to timen- 1), 
time executes timex timen number of times and prints out number 
of conses/timen, and computation time/timen. This is useful for 
more accurate measurement on small computations, e.g. 


–ТТМЕ ( (COPY (QUOTE (A B C))) 10) 
30/10 = 3 CONSES 

.055/10 = .0055 SECONDS 

(A B C). 


Some of the functions in this scction are TENEX/TOPS-20 or implementation dependent. They: may not be 


provided in other implementations of Interlisp. 
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date[-P 


idate[d] 


+ gdate[date;formatbits;strptr] 
+ 
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If timetype is 0, time measures and prints total real time as well as 
computation time, e.g. 


-TIME((LOAD (QUOTE PRETTY) (QUOTE PROP)) 1 0] 
FILE CREATED 7-MAY-71 12:47:14 


6с: 8 


582, 10291 FREE WORDS 
PRETTYFNS | 

PRETTYVARS 

3727 CONSES 

11.193 SECONDS 

27.378 SECONDS, REAL TIME 
PRETTY 


If timetyp = 3, time measures and prints garbage collection time as 
well as computation time, e.g. - 


-TIME((LOAD (QUOTE PRETTY) (QUOTE PROP)) 1 3] 
FILE CREATED 7-MAY-71 12:47:14 


GC: 8 | 

582, 1091 FREE WORDS. 

PRETTYFNS 

PRETTYVARS 

3727 CONSES 

10.597 SECONDS 

1.487 SECONDS, GARBAGE COLLECTION TIME 
PRETTY 


Another option is timetype=T, in which case time measures and 
prints the number of pagefaults. 


The value of time is the value of the last evaluation of timex. 


obtains date and time, returning it as single string in format "dd- 
mm-yy hh:mm:ss", where dd is day, mm is month, yy year, hh 
hours, mm minutes, ss seconds, е.р., "14-MAY-71 14:26:08". 


d is a date and time string. Value of idate is d converted to a 
number such that if datel is before (earlier than) date2, then 
idate[datel] < idate[date2]. If d=NIL, idate returns idate[date[]]. 


Interlisp-10 function for obtaining time-date formatted string, date 
is in internal date-and-time format. If NIL, current time and date 


In Interlisp-10, date will accept formatbits as an argument, which can be used to specify other formats, e.g., day of 


week, time zone, etc., as described in the JSYS manual. 
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clock[n] 


dismiss[n] 


conscount[n] 


boxcount[type;n] 


Measuring Functions 


is used, i.e. value of idate[] formatbits is 36 bit quantity to be 

passed to TENEX/TOPS 20 time-date conversion routines (see 
ISYS manual.) For example, formatbits=-1 gives a “long” date, e.g. 
"FRIDAY, JUN 16, 1978, 23:41:52-РОТ".3 If 
formatbits=NIL, defaults to a value which will produce the same 
format as that of да, ie. "dd- mm- yy hh:mm:ss". strptr is ап 
optional string pointer to be reused.4 


for n=0 current value of the time of day clock i.e., number of 
milliseconds since last system start up. 


for n=1 value of the time of day clock when the user started 
up this Interlisp, i.e., difference between clock[0] and 
clock[1] is number of milliseconds (real time) since this 
Interlisp was started. 


forn=2 number of milliseconds of compute time since user 
started up this Interlisp (garbage collection time is 
subtracted off). 


for n=3 number of milliseconds of compute time spent in 
garbage collections (all types)? 


In Interlisp-10, dismisses program for n milliseconds, during which 
time program is in a state similar to an I/O wait, 1.е., it uses по 
CPU time. Can be aborted by control-D, control-E, or control-B. 


conscount[] returns the number of conses since Interlisp started up. 
If n is not NIL, resets conscount to n. 


In Interlisp-10, number of boxing operations (see Section 13) since 
Interlisp started up. If type=NIL, returns number of large. integer 


boxes; type— FLOATING, returns number of floating boxes If n is 


not NIL, resets the corresponding counter to n. 


The dateformat package (Section 24) provides a convenient way of specifying the format bits in terms of keywords. 


gdate will TUS the characters returned by this one. Note that this mo кы jane is also used by several 


other functions in this section. 


In Interlisp-10, this number is directly accessible via the COREVAL GCTIM. 


In Interlisp-10, these counters are directly accessible ма the COREVALs IBOXCN and ҒВОХСМ, 
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. gcetrp[-] number of conses to next garbage collection of lists, i.e., number of 


list words not in use. Note that an intervening garbage collection 
of another type could collect as well as allocate additional list 
words. ӛсе Section 3. | 


gctrp[n] can be used to cause an interrupt when value of gctrp[]=n, 
see Section 10. 


pagefaults[] | In Interlisp-10, number of page faults since Interlisp started ор. 


1020 ] - returns control to operating system.’ Іп Interlisp-10, a subsequent 

| | | CONTINUE command will enter the Interlisp-10 program, return 
NIL as the value of the call to logout, and continue the 
computation exactly as if nothing had. happened, 1.е., logout is a 
programmable control-C. 


logout[] will not affect the state of any open files. 


21.2 BREAKDOWN? 


Time gives analyses by computation. Breakdown is available to analyze the breakdown of 
computation time (or any other measureable quantity) function by function. The user calls 
breakdown giving it a list of functions of interest. These functions are modified so that they keep 
track of the "charge" assessed to them. The function brkdwnresults gives the analysis of the 
statistic requested as well as the number of calls to each function? Sample output is shown below. 


-BREAKDOWN(SUPERPRINT SUBPRINT COMMENT1) 
(SUPERPRINT SUBPRINT COMMENT1) 
«PRETTYDEF((SUPERPRINT) FOO) 


F00.;3 
-BRKDWNRESULTS( ) | | 
. FUNCTIONS TIME # CALLS PER CALL x 
 SUPERPRINT 8.261 365 0.023 20 
SUBPRINT 31.910 141 0.226 76 
.COMMENT1 1.612 8 0.201 4 
TOTAL 41.783 | 514 0.081 
NIL 


The procedure used for measuring is such that if one function calls other and both are "broken 
down’, then the time (or whatever quantity 15 being measured) spent in the inner function is по! 


7 In Interlisp-10, if Interlisp was started as a subsidiary fork (see subsys, page 21.7), control is returned to the higher 
fork. | 
8772; breakdown was written by W. Тейсітап, and extended by L. Р. Deutsch. 
9 
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results, but instead to return them in the form of a list of elements of the form (name # calls valuc), e.g. for the 


с example shown above, this list would ~ be 
((SUPERPRINT 365 8261)(SUBPRINT 141 31910) (СОММЕМТі 8 1612)). 
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charged to the outer function as well.!° 


To remove functions from those being monitored, simply unbreak the functions, thereby restoring 


. them to their original state. То add functions, call breakdown on the new functions. This will not | 


reset the counters for any functions not on the new list. However breakdown[] can be used for 
zeroing the counters of all functions being monitored. 


To use breakdown for some other statistic, before calling breakdown, set the variable brkdwntype 
to the quantity of interest, e.g, TIME, CONSES, etc, or a list of such quantities. Whenever 
breakdown is called with brkdwntype not NIL, breakdown performs the necessary changes to its 
internal state to conform to the new analysis. In particular, if this is the first time an analysis is 
being run with a particular statistic, a measuring function will be defined, and the compiler will be 
called to compile 11 The functions being broken down will then be redefined to call this 
measuring function. When breakdown is through initializing, it sets brkdwntype back to NIL. 
Subsequent calls to breakdown will measure the new statistic until brkdwntype is again set and a 
new breakdown performed. Sample output is shown below: 


-SET(BRKDWNTYPE (TIME CONSES)) 

(TIME CONSES) 

-BREAKDOWN(MATCH CONSTRUCT) 

(MATCH CONSTRUCT) 

+FLIP((ABCDEFGHC2Z) (.. $1 .. 42 ..) (.. #3 ..)) 
(AB DE F GHZ) | 


-RESULTS( ) | | 
FUNCTIONS TIME # CALLS PER CALL X 
MATCH 0.036 1 0.036 54 
CONSTRUCT 0.031 1 0.031 46 
TOTAL 0.067 2 0.033 
FUNCTIONS СОМЅЕ5 4 CALLS PER CALL x 
MATCH 32 1 32.000 40 
CONSTRUCT 49 1 49.000 60 
TOTAL 81 2 40.500 

NIL 


The value of brkdwntype is used to search the list brkdwntypes for the information necessary to 
analyze this statistic. The entry on brkdwntypes corresponding to brkdwntype should be of the 
form (type form function), where form computes the statistic, and function (optional) converts the 
value of form to some more interesting quantity, e.g. 
(TIME (CLOCK 2) (LAMBDA (X) (FQUOTIENT X 1000))) measures computation time and 
reports the result in seconds instead of milliseconds. 1f brkdwntype is not defined on brkdwntypes, 
an error is generated.  brkdwntypes currently contains entries for TIME, CONSES, 
PAGEFAULTS, BOXES, and FBOXES. | 


10 breakdown will not give accurate results if a function being measured is not returned from normally, е.р., a lower 
retfrom (or error) bypasses it. In this case, all of the time (or whatever quantity is being measured) between the time 
that function is entered and the time the next function being measured is entered will be charged to the first 
function. 

11 


The measuring functions for TIME, CONSES, BOXES, and FBOXES have alrcady been compiled. 
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MORE ACCURATE MEASUREMENT 


Occasionally, a function being analysed is sufficiently fast that the overhead involved in measuring 
it obscures the actual time spent in the function. If the user were using time, he would specify a 
value for timen greater than 1 to give greater accuracy. А similar option is available for 
breakdown. The user can specify that a function(s) be executed a multiple number of times for 
each measurement, and the average value reported, by including a number in the list of functions 
given to breakdown, e.g, BREAKDOWN(EDITCOM EDIT4F 10 EDIT4E EQP) means normal 
breakdown for editcom and edit4f but executes (the body of) edit4e and eqp 10 times each time 
they are called. СОЕ course, the functions so measured must not cause. any harmful side effects, 
since they are executed more than once for each call. The printout from results will look the same 
as though each function were run only once, except that the measurement will be more accurate. 


Another way of obtaining more accurate measurement is to expand the call to the measuring 
function in-line. If the value of brkdwncompflg is non-NIL (initially NIL), then whenever a 


. function is broken-down, it will be redefined to call the measuring function, and then recompiled. 


The measuring function is expanded in-line via an appropriate macro. In addition, whenever 
brkdwntype is reset, the compiler is called for ай functions for which brkdwncompflg was set at the 
time they were originally broken-down, і.е. the setting of the flag at the time a function is broken- _ 
down determines whether the call to the measuring code is compiled in-line. 


21.3 INTERFORK COMMUNICATION IN INTERLISP-10 
The functions described below permit two forks (one or both of them Interlisp-10) to have a 


common area of address space for communication by providing a means of E a block of 
storage guaranteed not to move during garbage collections. 


getblk[n] Creates a block n pages in size (512 words per page). Value is the 
| address of the first word іп the block, which is a multiple of 512 
Since the block will always begin at a page boundary. If not 
enough pages are available, generates the error ILLEGAL OR 
IMPOSSIBLE BLOCK. 


Note: the block сап be used for storing unboxed numbers only. 


To store a number in the block, the following function could be used: 
[SETBLOCK (LAMBDA (START М X) (CLOSER (IPLUS (LOC START) М) X] 


Some boxing and unboxing can be avoided by making this function compile open via a 
substitution macro. 


Note: getblk should be used sparingly since several unmovable regions of memory can make it 


difficult or impossible for the garbage collector to find a contiguous region large enough for 


expanding array space. 


relblk[address;n] releases a block of storage beginning at address and extending for n 
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pages. Causes an error ILLEGAL OR IMPOSSIBLE BLOCK if any 
of the range is not a block. Value is address. 


21.4 SUBSYS" 


This section describes a function, subsys, which permits the user to run a TENEX/TOPS 20 
subsystem, such as SNDMSG, SRCCOM, TECO, or even another Interlisp, from inside of an 
Interlisp without destroying the latter. In particular, SUBSYS(EXEC) will start up a lower exec, 
which will print the operating system herald, followed by @. The user can then do anything at 
this exec level that he can at the top level, without affecting his superior Interlisp. For example, 
he can start another Interlisp, perform a sysin, run for a while, type a control-C returning him to 
the lower exec, RESET, do a SNDMSG, etc. The user exits from the lower exec via the command 
QUIT,’ which will return control to subsys in the higher Interlisp. Thus with subsys, the user 
need not perform a sysout to save the state of his Interlisp in order to use a TENEX/TOPS 20 
capability which would otherwise clobber the core image. Similarly, subsys provides a way of 
checking out a sysout file in a fresh Interlisp without having to commandeer another terminal or 
detach a job. 


While subsys can be used to run any subsystem directly, without going through an intervening 
exec, this procedure is not recommended. The problem is that control-C always returns control to 
the next highest EXEC. Thus if the user is running an Interlisp in which he performs 
SUBSYS(LISP), and then types control-C to the lower Interlisp, control will be returned to the 
exec above the first Interlisp. If the user elects to call a subsystem directly, he must therefore 
know how it is normally exited and always exit from it that way. 14 


Starting a lower exec does not have this disadvantage, since it сап only be exited via ми or 
POP, 1.е., the lower exec is effectively “errorset protected" against control-C. 


subsys|file/fork;incomfile;outcomfile;entrypointflg] | 
If file/fork=EXEC, starts up a lower exec, otherwise runs 
<SUBSYS>system, e.g. subsys[SNDMSG], subsys[TECO] etc. 5ирзучП 
is same as subsys[EXEC]. Control-C always returns control to next - 
higher exec. Note that more than one Interlisp can be stacked, but 
there is no backtrace to help you figure out where you are. 


incomfile and outcomfile provide a way of specifying files for input 
and output. incomfile can also be a string, in which case a 
temporary file is created, and the string printed on it. 


entrypointflg may be START, REENTER, or CONTINUE. NIL is 
equivalent to START, except when file/fork is a handle (see below) | 
in which case NIL is equivalent to CONTINUE. 


12 subsys was written Бу ЈУ. Goodwin and modified by D. С. Lewis. It is TENEX/TOPS 20 dependent and may not 


be available in implementations of Interlisp other than Interlisp-10, 


13 pop on TOPS-20. 


14 


Intcrlisp is exited via the function logout, TECO ма the command :Н, SNDMSG ма control-Z, and EXEC ма 
QUIT. | 
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The value of subs sys is a large integer which is a handle to the lower fork. The lower fork is not 
reset unless the user specifically does so using kfork, described below. 5 ір subsys is given as its 
first argument the value of a previous call to subsys, 16 it continues the subsystem run by that call. 
For example, the user can do (SETQ SOURCES (SUBSYS ТЕСО)), load up the TECO with a 
big source file, massage the file, leave TECO with ;H, run Interlisp for awhile (possibly including 
other calls to subsys) and then perform (SUBSYS SOURCES) to return to TECO, where he will 
find his file loaded and even the TECO pointer position preserved. 


Note that if the user starts a lower EXEC, in which he runs an Interlisp, control-C’s from the 
Interlisp, then QUIT from the EXEC, if he subsequently continues this EXEC with s == ће сап 
reenter ог continue the Interlisp. 


Note also that calls to subsys can be stacked. For example, using subsys, the user can run a lower 


. Interlisp, and within that Interlisp, yet another, etc., and ascend the chain of Interlisps using logout, 


and then descend back down again using subsys. 
For convenience, subsys[T] continues the last subsystem run. 


SNDMSG, LISP, TECO, and EXEC, are all LISPXMACROS which perform the corresponding calls 
to subsys. CONTIN is a LISPXMACRO which performs subsys[T] thereby continuing the last 
subsys 


kfork[fork] = accepts a.value from subsys and kills it (RESET іп TENEX 
| | terminology). If subsys[fork] is subsequently performed, an error is 
generated. kfork[T] kills all outstanding forks (from this Interlisp). 
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fildir[filegroup;-] | filegroup is a file group descriptor, i.e., it can contain stars. fildir 
| | returns a list of the files which match filegroup, a la the 
DIRECTORY command, e.g., (FILDIR (QUOTE *.COM;0)). 


_ loadav[] | : returns current load average as a floating point number (this 


number is the first of the three printed by the SYSTAT command). 


erstrfern;-] — | егп is an error number from a JSYS fail return. ern=NIL means 
the most recent error. erstr returns the operating system error 
diagnostic as a string. 


15 The fork is also reset when Ше handle is no longer accessible, i.e., when nothing in Ше intethisp system points to it. 
Note that the fork is accessible while the handle remains on the history list. 


16 Must be the exact same large number, i.e., ед. Note that if the user neglects to set a variable to the value of a call to 
subsys, (and has performed an intervening сай -so that subsys[ T] will not work), he can still continue this subsystem 
by obtaining the value of the call to subsys for the history list using the function valueof, described in Section 22. 


17 The EXEC lispxmacro is defined to save its value оп lastexec so that subsequent EXEC commands will restart the 
same exec, | 
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jsys[n;acl1;ac2;ac3;resultac] 


username[a] 


usernumber[a;-] 


hostnamefhostn] 


hostnumber[] 


systemtype[] 


tenex[str;fileflg] 
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loads (unboxed) values of acl, ac2, and ac3 into appropriate 
accumulaters, and executes JSYS number №18 ЈЕ acl, ac2, or 
ac3=NIL, 0 is used. Value of jsys is the (boxed) contents of the 
accumulator specified by resultac, i.c., 1 means acl, 2 means ас2, 
and 3 means ac3, with NIL equivalent to 1. Compiles open if n is 
itself a small integer, and resultac is a small integer, or NIL. 19 


If a=NIL, returns login directory name; if а= T, returns connected 
directory name; if a is a number, username returns the user name 


corresponding to that user number. In all cases, the value is а. 


string. 


If a=NIL, returns login user number; if a=T, returns connected 
user number; if a is a literal atom or string, usernumber returns the 
number of the corresponding user, or NIL if no such user exists.2Ü 


returns hostname as a string for host number hostn, e.g. "PARC- 
MAXC2", "BBN-TENEXD," etc. If hostn=NIL, local host is used. 
If local host is not an arpanet host, value is NIL. Value is also NIL 
if hostn is not a valid host number. 


ruturns host numer of local host, or NI L, of local host is not an . 


arpanet host. 
for Interlisp-10, returns either TENEX or TOPS 20. 


Starts up a lower exec (without a message) using, subsys, апа then if 
fileflg - NIL unreads str, followed by "QUIT"! (using bksysbuf, 
described in Section 14). The value of tenex is T if all of str is 
actually processed/read by the lower exec, NIL if the user 
control-C's and manually QUIT's back to Interlisp. 


If the JSYS causes a trap, the message TRAP AT LOCATION nnnnnn is printed by the operating system, followed 


by JSYS ERROR: and the operating system diagnostic. The user is then talking to the operating system exactly as 
though control-C had been typed. If the user then continues using the CONTINUE command, an Interlisp error is 
generated, JSYS ERROR, and control then proceeds the same as for any other flavor of error, ie. unwinds to last 
errorset or goes into a break as described in Section 16. 


19 


20 


The cjsys package (Section 24) enables calling jsyses by their corresponding name, rather than their number. 


On TOPS-20, there is a difference between the user number, which is associated with the job, and the directory 


number, which is associated with the file system. Therefore, on TOPS-20, usernumber takes an extra ацшы which, 
if T, says to return the directory number rather than the user number. 


2l 


"POP" for Interlisp on TOPS-20. 
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If fileflg- T, tenex passes the string as the second argument to 
subsys, instead of unreading it. This has the advantage that str can 
be of any length, and also that typeahead will not interfere with the 
call to the lower exec. The disadvantage is that tenex cannot tell 
whether the commands to the lower exec terminated successfully, or 
were aborted. Thus, if fileflg — T, the value of tenex is always T. 


For example, listfiles (Section 14) is implemented using tenex, with fileflg = NIL, so listfiles can tell 
if listings actually were completed. The lispxmacro SY, which does a SYSTAT, is implemented as 
TENEX[ "SY"; Т], so that the user can type ahead. 


MANIPULATING TENEX FILE DIRECTORIES FROM INTERLISP-10 


The following function allows the user to conveniently specify and/or program a variety of 
directory operations: 


directory[filegroup; commands; defaultext;defaultvers;-]? 


| e 
в 


РАЏ5Е 
PROMPT mess 


SIZE 


22 


23 . 


filegroup is either [1] NIL (which is equivalent to *.*; ‚ *); ог [2] ап 
atom which сап contain $’s ог *’s (equivalent) which match any 
number of characters? or ?'s which match a single character, or 
else [3] filegroup is a list of the form (filegroup + filegroup), 
(filegroup - filegroup), or (filegroup * filegroup), ^ e.g., (T$ + $L) 
will match with any file beginning with T or ending in L, 
(T$ - *.COM) matches all files that begin with T and are not 
. COM files. 


For each file that matches, each command in commands is executed 
with the following interpretation: 


apply fn to the JFN for each file; if fn returns NIL, abort 
command processing for this file.” 


print file name. 


wait for user to type any char (good for display if you want to 
ponder). 


prompts with mess; if user responds with No, abort command 
processing for this his file. 


print file size. 


directory was written by L.M. Masinter. 


not necessarily trailing characters, e.g., F$1 matches FOO1 and FIE1. 


24 оң can be used for +, and AND for *.- 


25 


If fn is a function of two arguments, it will be passed the name of the file as its second argument. 
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TRIMTO n | deletes all but п versions of Ше (а > 0). | 
` OUT file directs output to file. | 
COLLECT | adds file on value list. In this case the value of directory will be 
the list of files (complete file names) collected. 
DATE | prints date the file was last written. 
DELETE deletes file. 


The value of directory is NIL if no COLLECT command is 
specified, otherwise the list of files “collected”. 


DELETED prints out those files that have been deleted. 


UNDELETE undeletes the indicated files that have been deleted. 


directory uses dircommands to correct spelling, which also provides a way of defining abbreviations - 
and synonyms (see Section 17 оп spelling lists). Currently the following abbreviations are. 


recognized: 

TI | same as DATE 

DEL same as DELETED 

DEL? + | зате 25 PROMPT "delete?" DELETE 
COLLECT? same as PROMPT "?" COLLECT 


There is also a lispxmacro DIR which calls the function directory: 


DIR group commands calls the function directory with (P . commands) as the command 
list and * and * as the default extension and default version 
respectively. 


For example, to DELVER only those files which you ok, do DIR group PROMPT "?" TRIMTO 1. 


21.6 JFN FUNCTIONS IN INTERLISP-10 


JFN stands for job file number. It is an integral part of the TENEX file system and is described _ 


in [Murl], and in somewhat more detail in the TENEX JSYS manual. In Interlisp-10, the 
following functions are available for direct manipulation of JFNs: mE 


opnjfn[file;access] returns the ЛЕМ for file. If file not open, generates a FILE NOT 
OPEN error. access=NIL, INPUT, OUTPUT, or BOTH as 
described іп discussion of openp. For example, 


(JSYS 51Q (OPNJFN FILE) BYTE) will write a byte on a file, 
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jfns[jfn;ac3;strptr] 
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while (JSYS 500 (ОРМЈЕМ FILE) NIL NIL 2) will read one 
byte. 


sets up а "long" call to GTJEN (see JSYS manual). file is a file 


name possibly containing control-F and/or <esc>. ext is the 
default extension, v the default version (overriden if file specifies | 
extension/version, e.g., F00.COM;2). flags is as described on page 


17, section 2 of JSYS manual file and ext may be strings ог 


atoms; v and flags must be numbers. Value is JFN, or NIL on 
errors. | 


releases jfn. B fn[- 1] releases all J EN’ s which do not specify open 
files. Value of пут is T. 


converts jfn (a small number) to а file name. ac3 is either NIL, 
meaning format the file name as would openp or other Interlisp-10 _ 
file functions, or else is a number, meaning format according to 
JSYS manual. The value of jfns is atomic except where enough 
options are specified by ac3 to exceed atom size. In this case, the - 
value is returned as a string. 


strptr is an optional string pointer to be reused. In this case, (ће 
string characters are stored іп ап internal scratch string, 


macscratchstring, so that a subsequent call to jfns will overwrite the 


characters returned by this one. The value of jfns when s Strptr is 
supplied is always a string. | 


Тһе following function is available іп Interlisp-10 for specialized Ме applications: 


_ openf[file;x] 


opens. file. x is a number whose bits specify the access and mode - 
for Ме, 1.е., х corresponds to the second argument to the TENEX 
JSYS OPENF (see JSYS Manual). Value is full name of file. 


The first argument to openf can also be a number, which is then 
interpreted as a JFN. openf does not affect the primary input or 
output file settings, and does not check whether the file is already 
open - i.e., the same file can be opened more than once, possibly 
for different purposes. 


+ Note that for almost all applications the function openfile (Section 14) provides a more convenient 
+ (and implementation independent) way of opening files. | 
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21.7 PMAP PACKAGE% 


This facility allows paged access to files in Interlisp-10. .It manages a set of paging buffers as a 
least-recently-used queue, with each buffer being a full-page block (see getblk, Section 3). Facilities 
are provided for allocating and deallocating buffers, locking down pages, mapping a given page of 
the file into core, and getting the in-core location to which a given word of the file has been 
mapped. Any number of files can be mapped in at one time. 


The following scenario illustrates the use of these facilities: The user first opens the file (or files) 
that he wants to access by page-mapping using any of the ordinary file-opening functions. Then, 
to exàmine a particular word in one of the files, the user simply gives the word number and the 
files name to the function mapword, which returns a pointer to the in-core location that that word 
is mapped to (i.e. the address as an unboxed number). When he has finished processing, the user 
simply closes the file (e.g. using closef) and the buffers are automatically unmapped. 


The basic functions are: 


addbuffer[temp;errorflg] _ Initially, a single buffer is allocated, so that page-mapping may be 


done without further initialization. More buffers can be allocated. 
by addbuffer, which may help to avoid thrashing. addbuffer 


attempts to allocate a single new buffer, and returns T if successful. 
If there is not enough space to allocate a new buffer, then if 
errorflg is NIL, addbuffer simply returns NIL. Otherwise, addbuffer 

causes an error UNABLE ТО ALLOCATE PMAP BUFFER, | . 


If temp— T, the buffers are allocated on a "temporary" basis: 


allocation takes place via a resetsave whose restoration form will de- 
allocate the buffers. 


mapbuffercount[onlyunlocked] value is the number of buffers currently allocated. If 
onlyunlocked=T, counts only unlocked buffers; otherwise, counts 
all buffers. Thus, to insure that at least 3 (unlocked) buffers are 
allocated, the user could perform (while (MAPBUFFERCOUNT n 
1t 3 do (ADDBUFFER NIL T)). 


mappage[page # ; file] the primitive function for mapping in pages from file into the 


queue of buffers. рарс is a page number in file. The value of - 
mappage is a pointer to the word in core at which the first word of- 


the page is located, which will always be at a page-boundary (i.e. 
the pointer will print as # xxx000). 


If file is NIL, the value of defaultmapfile is uscd. file may also be 


a fork handle (і.е. a value of su bsys s), in which case the реше 
page from that fork will be mapped in. 


26 


The PMAP package was written бу R. M. Kaplan and L. M. Маѕіпісг, 
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 mapword[fileadr;file] 


wordoffset[ptr;n] | 
wordcontents[ptr] 
setwordcontents[ptr;n] 


clearmap[file;pages;release] | 
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тарраре searches the buffers to see if the given page for the given 


file has already been mapped in. If so, it returns the core address 
to which it was previously mapped. Otherwise, it replaces Ше. 


previous contents of Ше least-recently-used buffer with the specified 
file page. It is important to note that the contents of a given core 


buffer are not guaranteed across calls to mappage, unless the page 
has been locked down via lockmap. mappage compiles open, and in 
the case where the desired page is already in the buffer it is quite _ 


efficient. 


mappage will allocate an additional buffer if no unlocked buffers 
are available (and the desired page is not already mapped in), | 


like mappage, except that it allows the specification of a 
word-address in file, not just a page number. mapword determines 
what page that address is on, maps that page into a buffer (using 
mappage), and returns a pointer into the middle of the buffer 


where the indicated word appears. The rest of the words on the 


same file page appear at the appropriate wordoffsets from the value 
returned by mapword. 


If ptr is a pointer into a buffer as returned by mappage or - 

mapword, wordoffset[ptr;n] returns a pointer to the nth following | 
word. For example, mapword could be written as an wordoffset of - 
a mappage. wordoffset compiles open. 


Returns the contents of the word at ptr as an integer. For example, 
wordcontents[mapword[10;file]] will return the value stored in word 
10 of a (binary) file. wordcontents[ptr] is equivalent to- 


openr[loc[ptr]]. wordcontents compiles open. 


Sets the contents of the word pointed to by ptr to be the number 


п. Interpreted, setwordcontents checks that ptr actually is a pointer | 


as returned by mappage or mapword. setwordcontents compiles 
open with no error checks. 


file specifies a file or fork as for mappage, or it is T. pages is a 


single page number or a list of page numbers. clearmap unmaps 


any of those pages that are currently mapped in,^ making those | 
buffers available for other mappings. file=T means all files; 
pages=NIL means all pages. Thus clearmap[T] will completely | 
clcar the buffers. | 


whether or not they are currently locked, i.c. clearmap takes precedence over lockmap. | 
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If release=T, then not only will the buffers containing the specified 
pages be unmapped, but the buffers themselves will be released, i.e. 
returned to the Interlisp storage manager. 


lockmap[ptr] For those situations in which a program needs prolonged access to 
a particular file page, lockmap can be used to prevent mappage 
from shifting or unmapping the contents of the given core page. 
ptr is a pointer into a mapped page (i.e. a value of mapword or 
mappage). lockmap locks the indicated page in core until a 
corresponding unlockmap has been performed. Value is ptr. 


unlockmap[ptr; 12] ptr is a pointer into a mapped page. unlockmap removes the most 
recent lock for that page if flZg=NIL, and all locks if flg=T. 


21.8 TYPESCRIPT FILES 


A typescript file is a "transcript" of all of the input and output on a terminal. The following 
function enables transcript files for Interlisp. 


dribble[filename;appendflg;-]? Opens filename and begins recording Ше ғ Уаше 15 о14 
typescript Ше if any, otherwise NIL. певане o T, the 
typescript will be appended to the end of filename. dribble[] 
closes the typescript file?! 


dribble processes a line buffer at a time. Thus, the typescript produced is somewhat neater than 
that generated by TELNET because it does not show characters that were erased via control-A or 
control-Q. Note that the typescript file is not included in the list of files returned by орепрђ, nor 
will it be closed by a call to closeall or closef. Only dribble[] closes the typescript file. 


dribblefile[] returns name of current typescript file, if any, otherwise NIL. 


21.9 DISPLAY TERMINALS 


The value of the variable displaytermflg indicates whether the user is running on a display terminal 
or not. displaytermflg is used in various places in the system, e.g., prettyprint, helpsys, etc., 


28 ү a page has been locked twice, it must be unlocked twice before it is available for reuse. 

29 dribble was written by D. C. Lewis. 

30 dribble also takes an extra argument, thawedflg. If thawedflg — T, the file will be opened in "thawed" mode, 
31 | 


Only one typescript file сап be active at any one point; 1.с., е followed Бу dribble[file2] will cause filel to 
be closed. 
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primarily to decide how much information to present to the user (more on a display terminal than 
on a hard copy terminal) displaytermflg is initialized to the value of displaytermpf], whenever 


Interlisp is 5 (ге): -entered, and айег returning from a sysout. 


displaytermp] = value is T if user is оп a display terminal, NIL otherwise. In 
2. | Interlisp-10, displayterm rmp is defined to invoke the appropriate jsys 
to cheek the user’s terminal type. 


21.10 GAINSPACE 


For users with large programs and data bases, the user may sometimes find himself in a situation 
where he needs to obtain more space, and is willing to pay the price of eliminating some or all of 
the context information that the various user-assistance facilities such as the programmer’s assistant, - 
file package, CLISP, etc., have accumulated during the course of his session. The following 


function is available for this purpose. 


| gainspace[] - _ . walks the user through a menu, prompting him at each point, and 


allowing him to specify what can be discarded and what should be 
retained, e.g.: | 


GAINSPACE() 


purge history lists ? Yes 


purge everything, or just the properties, e.g. , SIDE, LISPXPRINT, etc. ? 


just the properties 


discard definitions on property lists ? Yes 
discard old values of variables ? Yes 

erase filepkg information ? No 

erase properties ? No 


etc. 


gainspace is driven by the list gainspaceforms. Each element on gainspaceforms is of the form 


(precheck message form keylst). If precheck, when evaluated, returns NIL, gainspace skips to the - 
. next entry. For example, the user will not be asked whether or not to discard edita initialization if 


he has not initialized edita. Otherwise, askuser (Section 17) is called with the indicated message 
and the (optional) keylst. If the user responds No, 1е., askuser returns М, gainspace skips to the 


.. next entry. Otherwise, form is evaluated with the variable response bound to the value of askuser, | 


e.g., in the above example, if the user had responded with Everything, instead of Yes, to the 
"purge history lists" question, he would not have been asked the second question, because the 
form for this entry checks to see whether the value of response is Y or E. | 


. The "erase properties" entry on gainspaceforms is driven by a list smashpropsmenu. Each element 
on this list is of the form (message . props). The user is prompted with message (by авКивег), and 


if he responds Yes, props is added to the list smashprops. The "discard definitions on property 
lists" and "discard old values of variables" entries on gainspaccforms also add to smashprops. The 
user will not be prompted for any entry on smashpropsmenu for which all of thc corresponding 
properties are already on smashprops. smashprops is initially set to the value of smashpropstst. 
This permits the user to specify in advance those properties which he always wants to be discarded, - 
and not be asked about them subsequently. 
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After finishing all the entries on gainspaceforms, gainspace checks to see if the value of smashprops 
is non-NIL, and if so, does a mapatoms, 1.е., looks at every atom in the system, and erases the 
` indicated properties. 


Note that the user can change the entries on gainspaceforms or И and/or add new - 
entries to either, so that gainspace can also be used to purge structures that the user's programs 
have accumulated. 
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THE PROGRAMMER'S ASSISTANT! - 


22.1 INTRODUCTION 


“Тһе central idea of the programmer's assistant is that the user, rather than talking to a passive 
system which merely responds to each input and waits for the next, is instead addressing an active 
intermediary, namely his assistant Normally, the assistant is invisible to the user, and simply 
carries out the user's requests. However, since the assistant remembers what the user has told him, | 
the user can instruct him to repeat a particular operation or sequence of operations, with possible 
modifications, or to undo the effect of certain specified operations. Like DWIM, the programmer's. 
assistant is not implemented as a single function or group of functions, but is instead dispersed 
throughout much of Interlisp.? Like DWIM, the programmer's assistant embodies a philosophy and · 
approach to system design whose ultimate goal is to construct a programming environment which | 
would "cooperate" with the user in the development of his programs, and free him to concentrate 

more fully on the conceptual difficulties and creative aspects of the problem he is trying to solve. 


EXAMPLE 
The following dialogue, taken from an actual session at the console, gives the flavor of the 
programmer's assistant facility in Interlisp. The user is about to edit a function loadf, which 


contains several constructs of the form (PUTD FN2 (GETD F N1)). The user pum to replace 
each of these by equivalent MOVD expressions. 


The programmer's assistant was designed and implemented by W. Teitelman. It is discussed in [Tei4]. 


Some of the features of the programmer's assistant have been described elsewhere, е.р., the UNDO command in (һе 
editor, the file package, etc. 
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*EDITF(LOADFF] 0 — [1] 
-LOADF 
EDIT 
«рр 
= [LAMBDA (X Y) 
[COND . 
((NULL (GETD (QUOTE READSAVE))) 
(PUTD (QUOTE READSAVE) 
(GETD (QUOTE READ] 
(PUTD (QUOTE READ) 
(СЕТО (QUOTE REED))) 
(NLSETQ (SETQ X (LOAD X Y))) 
(QUTD (QUOTE READ) 
(GETD (QUOTE READSAVE))) 


X] 
*F PUTD (1 MOVD) [2] 
*3 (XTRR 2) B [3] 
-XTR | | | 
“ОР | [41 
0 P | 
(MOVD (QUOTE READSAVE) (QUOTE READ)) 
"(54 2 3) |. [5] 
* | 


At [1], the user begins to edit loadf? At [2] the user finds PUTD and replaces it by МОМО. He then 

shifts context to the third subexpression, [3], extracts its second subexpression, and ascends one 
level [4] to print and result. The user now switches the second and third subexpression [5], thereby. 
completing the operation for this PUTD. Note that up to this point, the user has not directly 
addressed the assistant. The user now requests that the assistant print out the operations that the 
user has performed, [6], and the user then instructs the assistant to REDO FROM F, [7], meaning 
repeat the entire sequence of operations 15 through 20. The user then prints the current 
expression, and observes that the second PUTD has now been successfully transformed. 


“77 FROM Е | | | [6] 
15. *Е PUTD 

16. "(1 МОМО) 

17. #3 

18. *(XTR 2) 

19. “0 

20. *(SW 2 3) 

*REDO FROM F [7] 
* р | 


(MOVD (QUOTE REED) (QUOTE READ)) 


3 We prefer to consider the programmer's assistant as the moving force behind this type of spelling correction (even 


though the program that docs the work is part of the DWIM package). Whereas correcting @PRINT to PRINT, or о 
XTRR to XTR docs not require any information about what this user is doing, correcting LOADFF to LOADF clearly 
required noticing when this user defined loadf. | 
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The user now asks the assistant to replay the last three steps to him, [8]. Note that the entire 
REDO FROM F operation is now grouped together as a single unit, [9], since it corresponded to a 
single user request. Therefore, the user can instruct the assistant to carry out the same operation 
again by simply saying REDO. This time a problem is encountered [10], so the user asks the 
assistant what it was trying to do [11]. 


#22 FROM -3 | [8] 
19. -. 
20. *(SW 2 3) | | 
21. REDO FROM Е | | [9] 
_ *F PUTD | | 
*(1 MOVD) 
“3 
*(XTR 2) 
0. 
*(SW 2 3) 
*REDO 
PUTO? zj | m "E по. 
*?? -1 CER аа | 2 |o [11] 
22. REDO | | | 
*F PUTD 


*(1 MOVD) 
*3 
*(XTR 2) 
“0 


The user then realizes the problem is that the third PUTD is misspelled іп the definition of LOADF 
(see page 22.2). He therefore instructs the assistant to USE @UTD FOR PUTD, [12], and Ше 
operation now concludes successfully. | 


*USE @UTD FOR PUTD | [12] 
ТЕ 
(МОМО (QUOTE READSAVE) (QUOTE READ) ) 
*t PP 
[LAMBDA (X Y) 
[COND 
((NULL (СЕТО (QUOTE READSAVE))) 
(MOVD (QUOTE READ) 
(QUOTE READSAVE] 
(MOVD (QUOTE REED) 
(QUOTE READ)) 
(NLSETQ (5ЕТО X (LOAD X Y))) 
(MOVD (QUOTE READSAVE) 
(QUOTE READ)) 
X] 
"ОК 


LOADF 


€ 


An important point to note here is that while the user could have defined a macro to execute this 
opcration, the opcration is sufficiently complicated that he would want to try out the individual 
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steps before attempting to combine them. At this point, he would already have executed Ше 
operation once. Then he would have to type in the steps again to define them as a macro, at 
which point the operation would only be repeated once more before failing. Then the user would 
have to repair the macro, or clse change @UTD to PUTD by hand so that his macro would work 
correctly. It is far more natural to decide after trying a series of operations whether or not one 
wants them repeated or forgotten. In addition, frequently the user will think that the operation(s) 
in question will never need be repeated, and only discover afterwards that he is mistaken, as occurs 
when the operation was incorrect, but salvageable: 


*р 

(LAMBDA (STR FLGCQ VRB) **COMMENT** (PROG 8 & 1Р1 8 LP2 & &)) 
-1 -1 Р 

(RETURN (COND &)) | | | | 

d" ((EQ BB (QUOTE OUT)) BB] ZEN 5 

өкілінің (% BB) (COND &)) 5. ss E21 

*UNDO | 

(-2 --) UNDONE 

*2 р 

(COND (EXPANS а & Т)) 

*REDO EQ 

"P. 


(COND (8 ВВ) (ЕХРАМ5 & 8 T) 
* 


Here the operation was correct, [1], but the context in which it was executed, m Was Yong. 


This example also illustrates one of the most useful functions of the programmer' У assistant: dts 
UNDO capability. In most systems, if a user suspected that a disaster might result from a particular 


22. Operation, e.g., an untested program running wild and chewing up a complex data structure, he 
. would prepare for this contingency by saving the state of part or all of his environment before 


attempting the operation. If anything went wrong, he would then back up and start over. 
However, saving/dumping operations are usually expensive and time consuming, especially 
compared to a short computation, and are therefore not performed that frequently, and of course 
there is always the case when diaster strikes as a result of a "debugged" or at least innocuous 
operation, as shown in the following example: 


«(МАРС ELTS (FUNCTION ( LAMBDA (X) (REMPROP X (QUOTE MORPH] [1] 
NIL 
«UNDO [2] 
MAPC UNDONE. | 
«USE ELEMENTS FOR ELTS | | | | [3] 
NIL 


€ 


The user types an expression which removes the property MORPH from every member of the list 
ELTS [1], and then realizes that he meant to remove that property only from those members of the 


list ELEMENTS, a much shorter list. In other words, he has deleted a lot of information that he 


actually wants saved. He therefore simply reverses the effect of the МАРС by typing UNDO [2], and 


= then does what he intended via the USE command [3]. 


22.2 OVERVIEW 


2 The programmer’s assistant facility is built around a memory structure called the "history list." The 
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history list is a list of the information associated with each of the individual ' events” that have 
occurred in the system, where each event corresponds to one user input.* For example, (XTR 2) 
([3] on page 22.2) is a single event, while REDO FROM F ([7] on page 22.2) is also a single cvent, 
although the latter includes executing the operation (XTR 2), as well as several others. 


Associated with each event on the history list is its input and its value, plus other optional 
information such as side-effects, formatting information, etc. If the event corresponds to a history 
command, e.g., REDO FROM F, the input corresponds to what the user would have had to type to 
execute the same operation(s), although the user's actual input, 1.е., the history command, is saved 
in order to clarify the printout of that event ([9] on page 22.3). Note that if a гав command 
event combines several events, it will have more than one value: 


For various reasons, there are two history lists: one for the editor, and one for lispx, which processes inputs to_evalqt 
and break, see page 22,34, 
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«(LOG (ANTILOG 4)) 


4.0 | 
-USE 4.0 40 400 FOR 4 
4.0 

. 40.0 
ARG NOT IN RANGE 
400 | 


USE -40.0 -4. 00007 -19. 

-40.0 
-4.00007 

-19.0 

USE LOG ANTILOG FOR ANTILOG 106 ІМ -2 АМО -1 


4. USE LOG ANTILOG FOR ANTILOG LOG IN -2 -1 
.*(ANTILOG (LOG 4.0)) 
4.0 
+(ANTILOG (LOG 40)) 
40.0 
-«(ANTILOG (LOG 400)) 
400.0 
-(ANTILOG (LOG -40.0)) 
40.0 
«(АМТ1106 (LOG -4.00007)) 
4.00007 | 
-(ANTILOG (LOG -19.0)) 
19.0 — 
3. USE -40.0 -4.00007 -19.0 
| «(LOG (ANTILOG -40.0)) 
| -40.0 
жоба «(LOG (ANTILOG -4.00007)) 
BE -4.00007 
INIM «(106 (ANTILOG -19.0)) 
- -19.0 
2. USE 4.0 40 400 FOR 4 
«(106 (ANTILOG 4.0)) 
4.0 
(LOG (ANTILOG 40.0) 
40.0 
«(106 (ANTILOG 400)) 


1. «(106 (ANTILOG 4)) 
4.0 


As new events occur, existing events are aged, and the oldest event is "forgotten." For efficiency, 
the storage used to represent thc forgotten cvent is cannibalized and reused in the rcpresentation of 
the new event, so the history list is actually a ring buffer. The size of this ring buffer is a system. 
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parameter called the 'time-slice.? Larger time-slices enable longer "memory spans," but tie up 
correspondingly greater amounts of storage. Since the user seldom needs really "ancient history," 
and a NAME and RETRIEVE facility is provided for saving and remembering selected events, a 
rclatively small time slice such as 30 events is more than adequate, although some users prefer to 
set the time slice as large as 100 events. 


Events on the history list can be referenced in a number of ways. The output on page 22.8 
shows a printout of a history list with time-slice 16. Тһе numbers printed at the left of the page 
are the event numbers. More recent events have higher numbers; the most recent event is event 
number 52, the oldest and about-to-be-forgotten event is number 37.6 At this point in time, the 
user can reference event number 51, RECOMPILE(EDIT), by its event number, 51; its relative 
position, -2 (because it occurred two events back from the current time), or by a "description" of 
its input, e.g, (RECOMPILE (EDIT)), or (& (EDIT)), or even just EDIT. As new events 
occur, existing events retain their absolute event numbers, although their relative positions change. 


Similarly, descriptor references may require more precision to refer to an older event. For 


example, the description RECOMPILE would have sufficed to refer to event 51 had event 52, also 
containing a RECOMPILE, not intervened. Event specification will be described in detail later. 


Initially 30 events. The time-slice can be changed with the function changeslice, page 22.40. 
When the event number of the current event is 100, the next event will be given number 1. (If the time slice is 
greater than 100, the "roll-over" occurs at the next highest hundred, so that at no time will two events ever have the 


same event number. For example, if the time slice is 150, event number 1 follows event number 200.) 


22.7 


Section 22: The Programmer's Assistant 


ef? 


252. ... HIST UNDO 

-RECOMPILE(HIST) 
ST 
HIST.COM 
-RECOMPILE(UNDO) 
ST 
UNDO. COM 

51. -RECOMPILE(EDIT) 
ST 
EDIT.COM 

50. «1060071 


49. MAKEFILES] 
(EDIT UNDO HIST) 
48. «EDITF(UNDOLISPX) 
UNDOLISPX | 
47. REDO GETD 
«СЕТО(ЕІЕ) 
(LAMBDA (Х) (МАРС X (F/L (PRINT Х)))) 
46. «UNDO 
FIE 
45. «6 ЕТО (ЕТЕ) 
(LAMBDA (Х) (МАРС X (FUNCTION (LAMBDA (Х) (PRINT x))))) 
44. €FIE] 
NIL 
43. «ОЕЕТМЕО((ЕТЕ (LAMBDA (X) (МАРС X (F/L (PRINT n»n 
(FIE) 
42. REDO GETD 
eGETD(FIE) 
(LAMBDA (Y) Y) 
41. «UNDO 
MOVD 
40. REDO GETD 
«6 ЕТО (ЕТЕ) 
(LAMBDA (X) Х) 
39. «MOVD(FOO ЕТЕ) 
ЕТЕ 
38. «DEFINEQ((FOO (LAMBDA (X) Х))) 
(ЕОО) 
37. «GETD(FIE) 
(LAMBDA (Ү) Y) 


The most common interaction with the programmer's assistant occurs at the top level evalqt, or in 
a break, where the user types in expressions for evaluation, and sees the values printed out. In this 
mode, the assistant acts much like a standard LISP evalqt, except that before attempting to 
evaluate an input, the assistant first stores it in a new entry on the history list. Thus if the 
operation is aborted or causes an crror, the input is still saved and available for modification 
and/or reexecution. The assistant also notes new functions and variables to be адаса to its spelling 
lists to enable future corrections. Then the assistant exccutes the computation (i.c., evaluates the 
form or applics the function to its arguments), saves the value in the entry on the history list 
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Overview 


corresponding to the input, Lund prints the result followed by a prompt character to indicate itis 


again ready for input. 


If the input typed by the user is recognized as a history command, the assistant takes special 
action? Commands such as UNDO, ??, NAME, and RETRIEVE are immediately performed. 
Commands that involved reexecution of previous inputs, е.р., REDO and USE, are achieved by 
computing the corresponding input expression(s) and then unreading them. The effect of this 
unreading operation is to cause the assistant's input routine, lispxread, to act exactly as though 
these expression were typed in by the user. Except for the fact that these inputs are not saved on 
new and separate entries on the history list, but associated with the history command that 
generated them, they are processed exactly as though they had been typed. 


The advantage of this implementation is that it makes the programmer's assistant a callable facility 
for other system packages as well as for users with their own private executives. For example, 
breakl accept user inputs, recognizes and executes certain break commands and macros, and 
interprets anything else as Interlisp expressions for evaluation. То interface breakl with the 
programmer's assistant required three small modifications to breakl: (1) input was to be obtained 
via lispxread instead of read; (2) instead of calling eval or apply directly, breakl was to give those 
inputs it could not interpret to lispx, and (3) any commands or macros handled by breakl, i.e., not 
given to lispx, were to be stored on the history list by breakl by calling the function historysave, a 
part of the assistant package. 


Thus when the user typed in a break command, the command would be stored on the history list 
as а result of (3). If the user typed in an expression for evaluation, it would be evaluated as 
before, with the expression and its value both saved on the history list as a result of (2). Now if 
the user entered a break and typed three inputs: EVAL, (CAR IVALUE), and OK, at the next 
break, he could achieve the same effect by typing REDO FROM EVAL. This would cause the 


assistant to unread the three expressions EVAL, (CAR !VALUE), and OK. Because of (1), ће 


next "input" seen by breakl would then be EVAL, which breakl would interpret. Next would 
come (CAR !VALUE), which would be given to lispx to evaluate, and then would come OK, which 


break] would again process. Thus, by virtue of unreading, history operations will work even for- 


those inputs not interpretable by lispx, in this case, EVAL and OK. 


The net effect of this implementation of the programmer's assistant is to provide a facility which is 
easily inserted at many levels, and embodies a consistent set of commands and conventions for 
talking about past events. This gives the user the subjective feeling that a single agent is watching 
everything he does and says, and is always available to help. | | 


using showprint (Section 14), so that if the value of sysprettyflg = T, the value will be prettyprinted. 


The function that accepts a user input, saves the input on the history list, performs the indicated computation of 
history command, and prints the result, is lispx. lispx is called by evalgt and breakl, and in most cases, is 
synonymous with "programmer's assistant." However, for various reasons, the editor saves its own inputs оп a history 
list, carries out the requests, i.e., edit commands, and even handles undoing independently of lispx. The editor only 
calls lispx to execute a history command, such as REDO, USE, etc. Therefore we use the term assistant (loosely) 
when the discussion applies to features shared by evalgt, break and the editor, and the term lispx when we are 
discussing the specific function. 


If the user defines a function by the same пате as a history command, a warning message 15 poned: to remind him 
that the history command interpretation will take precedence for type-in. | 
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22.3 EVENT SPECIFICATION 


All history commands use the same conventions and syntax for indicating which event or events on 
the history list the command refers to, even though different commands may be concerned with 
different aspects of the corresponding event(s), e.g., side-effects, value, input, etc. Therefore, before 
discussing the various history commands in the next section, this section describes the types of 
event specifications currently implemented. АП examples refer to the history list on page 22.8. 


An event address identifies one event on the history list. It consists of a sequence of "commands" 
for moving an imaginary cursor up or down the history list, much in the manner of the arguments 
to the @ command in break (see Section 15) The event identified is the one "under" the 
imaginary cursor when there are no more commands. (If any command fails, an error is generated 
and the history command is aborted.) 


The commands are interpreted as follows: 


n (n > 1) | move forward n events, ie. in direction of increasing event 
| number. If given as the first "command," n specifies the event 
with event number n. | | 


n (n < -1) move backward -n events. 


. *atom specifies ап event whose function matches atom (ie. for apply 

| format only) e.g, whereas ЕТЕ would refer to event 47, «ҒІЕ 
would refer to event 44. Similarly, ЕО510 would specify event 51, 
whereas «ЕО event 48. 


є next search is to go forward instead of backward, (if given as the 
first "command", next search begins with last, i.e., oldest, event on 
history 1150), ер, «< LAMBDA refers to event 38; 
MAKEFILES «€ RECOMPILE refers to event 51. 


F next object is to be searched for, regardless of what it is, e.g, Е -2 
looks for an event containing a -2. 


= | next object (presumably a pattern) is to be matched against values, 
instead of inputs, e.g., = UNDO refers to event 49; 45 = FIE refers 
to event 43; « = LAMBDA refers to event 37. „аз 


\ | | mE specifies the event last located. 


10 ie, ED<esc>. 
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SUCHTHAT pred specifies an event for which pred, a function of two arguments, 
| when given the input portion of the event as its first argument, and 
the event itself as its second argument, returns true. Eg, 
SUCHTHAT (LAMBDA (X Y) (MEMB (QUOTE *ERROR*) Y)) 

specifies an event in which an error occurred! — — 


atom where atom is the name of a command defined via the NAME 
command (page 22.21), specifies the event(s) defining atom. 


pat anything else specifies an event whose Input contains an expression 
that matches pat as described in Section 9. | 


| Note: each search skips the current event, іе., each command always moves the cursor. For 
example, if FOO refers to event n, FOO FIE will refer to some event before event n, even if there 
is a FIE in event n. | 


An event specification specifies опе or more events: 


FROM #1 THRU #2 the sequence of events from the © 

#1 THRU #2 event with address #1 through event with address #2,4 e.g., FROM 
СЕТО THRU 49 specifies events 47, 48, and 49. #1 can be more | 
recent than #2, e.g., FROM 49 THRU GETP specifies events 49, 48, 
and 47 (note reversal of order). 


FROM #1 TO #2 Same as THRU but does not include event #2. | 


#1 ТО #2 

ЕКОМ #1 same as FROM #1 THRU -1, e.g, FROM 49 specifies events 49, . 
50, 51, and 52. 

THRU #2 Same as FROM -1 THRU #2, e.g., THRU 49 specifies events 52, 


51, 50, and 49. Note reversal of order. 


TO #2 Same as FROM -1 TO #2. 

1 бее page 22.34 for discussion of the format of events оп the history list. 

12 If FOO is such a command, but the user wants to specify the event containing FOO, he can still use the event 
specification F FOO. 

13 The matching is performed by the function historymatch (page 22.40), which is initially defined to call editfindp but 
can be advised or redefined for specialized applications. 

14 


ie., the symbol #1 corresponds to all words between FROM and THRU in the event specification, and #2 to all 
words from THRU to the end of the event specification. For example, in FROM FOO 2 THRU ЕТЕ -1, #1 is 
(FOO 2), and #2 is (ЕТЕ -1). | 
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£1 AND #2 AND ... AND in | 

EE | ie, a sequence of event specifications separated by AND’ 5, e.g., 
FROM 47 TO LOGOUT would be equivalent to 47 AND 48 AND 
MAKEFILES. 


ALL #1 specifies all events satisfying ЖІ, ер, ALL LOAD, ALL 


SUCHTHAT ЕОО. 


empty ! . .ie. nothing specified, same as -1, unless last event у was an UNDO, in Е: 


which case same as -2.15 


оде _ | € is ап event specification and interpreted as above, but with 


respect to the archived history list, as specified on page 22.23. 


If no events can be found that satisfy the event specification, spelling correction on each word in 
the event specification is performed using lispxfindsplst as a spelling list, е.р., REDO 3 THRUU 6 
will work correctly. If the event ресе still rang to specify any events after spelling консо, 
ап еггог 15 generated. 


22.4 HISTORY COMMANDS. 


АШ history commands сап be input as either lists, or as lines (see readline, Section 14, and also 
| page 22.35). 


€ is used to denote an event specification. Unless specified otherwise, € omitted is the same as 
ф=-1, eg, REDO and REDO -1 are the same. 


REDO € — n = redoes the event or events specified by €, e.g., REDO FROM -3 
| | redoes the last three events. 


REDO ¢ N TIMES redoes the event or events specified by ¢ N times, e.g., REDO 10 
Ж TIMES redoes the last event ten times. 


REDO ¢ WHILE form redoes the specified events as long as the value of form is true, 
| form is evaluated before each iteration so if its initial value is NIL, 
nothing will happen. 


REDO € UNTIL form same as REDO € WHILE (NOT form). 


15 For example, if the user types (МСОМС FOO ЕТЕ), he сап then type UNDO, followed by USE NCONC1. 
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REPEAT ¢ | same as REDO € WHILE T, i.e, the event(s) are repeated until an 
error occurs, ог user types control- E or control-D. | 


REPEAT ¢ WHILE/UNTIL form 
same interpretation as REDO. 


For all history commands that perform multiple repetitions, the variable redocnt is initialized to 0 
and incremented each iteration. If the event terminates gracefully, 1.е., is not aborted by an error 
or control-D, the number of iterations is printed. _ 


USE exprs FOR args IN ¢ substitutes exprs for args іп €, and redoes the result, e.g., 
USE LOG ANTILOG FOR ANTILOG LOG IN -2 AND -1. 
Substitution is done by esubst, Section 9, and is carried out as 
described below. exprs and args can include non-atomic members. 


USE ехргѕу FOR args; AND ... AND ехрг FOR args, IN e 
. More general form of USE. command. See description. of 
substitution algorithm below. | 


Every USE command involves three pieces of information: the expressions to be substituted, the 
arguments to be substituted for, and an event specification, which defines the expression (щам) іп 
which the substitution takes різсе,16 4 
Any expression to be substituted сап be preceded by a |, meaning that the expression is to be 
substituted as a segment, e.g., LIST(A B С) followed by USE ! (X У 2) FOR B will produce 
(AX Y Z C), and USE | NIL FOR B will produce (A С). 


If args are omitted, i.e., the form of the command is USE exprs IN €, or just USE exprs (which is 
equivalent to USE exprs IN -1) and the event referred to was itself а USE command, the 
arguments and expression substituted into are the same as for the indicated USE command. Іп 
effect, this USE command is thus a continuation of the previous USE command. For example, on 
page 22.6, when the user types (LOG (ANTILOG э), followed by USE 4.0 40 400 FOR 4, 
followed by 

USE -40.0 -4.00007 -19., the latter command is equivalent to 

USE -40.0 -4.00007 -19. FOR 4 IN -2. 


If args are omitted and the event referred to was not a USE command, substitution is for the 
operator in that command, i.e., if a lispx input, the name of the function, if an edit command, the - 
name of the command. For example Те FF) followed by meee CALLS is equivalent to 
USE CALLS FOR ARGLIST. 


If IN ¢ is omitted, but args are specified, the first member of args is used for ¢, e.g., USE PUTD 


16 


The USE command is parsed by a small finite state parser to distinguish the expressions and ш For example, 
USE FOR FOR AND AND AND FOR FOR will be parsed correctly. 
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FOR QUTD is equivalent to USE PUTD FOR @UTD IN Е QUTD. 


If the USE Eod has the same number of expressions as arguments, the substitution procedure 
is straightforward, ie, USE X Y FOR U V means substitute X for U and Y for V, and is - 
equivalent to USE X FOR U AND Y FOR V. However, the USE command also permits 
distributive substitutions, i.e., substituting several expressions for the same argument. For example, 
USE A B C FOR X means first substitute A for X then substitute B for X (in a new copy of the 


‚ expression), then substitute C for X. The effect is the same as three separate USE commands. 


Similarly, USE A B C FOR D AND X Y 2 FOR W 15 equivalent to 
USE A FOR D AND X FOR W, followed by USE B FOR D ды М FOR М, followed by 


USE C FOR D АМО Z FOR W. USE A B C FOR D AND X FOR Y}? also corresponds to three 


substitions, the first with A for D and X for Y, the second with B for D, and X for Y, and the third 
with C for D, and again X for Y. However, USE A B C FOR D AND X Y FOR Z is ambiguous 


and will cause an error. Essentially, the USE command operates by proceeding from left to right 


handling each "AN D" separately. Whenever the number of рео exceeds the number of 
expressions available, the expressions multiply. | 


FIX € | puts the user in the editor looking at a сору of the input(s) for ¢, 
Whenever the user exits via, ок the result is unread and 
reexecuted exactly as with REDO. 


FIX is provided for those cases when the modifications to the input(s) are not of the type that can 


be specified by USE, 1.е., not substitutions. For example: 


-(DEFINEQ FOO (LAMBDA (X) (FIXSPELL SPELLINGS2 X 70] 


INCORRECT DEFINING FORM 
FOO | 


(DEFINEQ FOO (LAMBDA & &)) 
*(LI 2) 

“ок. 

(Ғ00) 

+ 


17 The Е is inserted to handle correctly - the case where the first member of args is a number, eg, 
USE 4.0 4.0 400 FOR 4. Obviously the user means find the event containing a 4 and perform the indicated 
substitutions, whereas USE 4.0 40 400 FOR 4 IN 4 would mean perform the substitutions in event number 4. 


18 Except when one of the arguments and one of the expressions are the same, e.g, USE X Y FOR Y X, or 
USE X FOR Y AND Y FOR X. This situation is noticed when parsing the command, and handled correctly, 


19  orUSE X FOR Y AND A B C FOR D. 
20 Thus USE A B C D FOR E F means substitute A for E at the same time as substituting B for F, then in another 
copy of the indicated expression, substitute C for E and D for Е. Note that this is also equivalent to 


USE A C FOR E AND B D FOR Р. 
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The user can also specify the edit command(s) to lispx, by typing - followed by the command(s) 
after the event specification, e.g, FIX - (LI 2). In this case, the editor will not type EDIT, ог 
. Wait for an OK after executing the commands. | | | | | 


IMPLEMENTATION OF REDO, USE, AND FIX 


The input portion of an event is represented internally on the history list simply as a linear 
sequence of the expressions which were read. For example, an input in apply format 15 а list 
consisting of two expressions, and an input in eval format is а list of just опе expression.” Thus if 
the user wishes to convert an input in a apply format to eval format, he simply n moves thé function 
name inside of the argument list: | 


-MAPC(FOOFNS (F/L (AND (EXPRP X) (PRINT X] 
NIL 

-EXPRP(F001) 

а 


-FIX МАРС 

EDIT — 

ер 

(МАРС (FOOFNS &) "<с.г.»")22 
“(МОМЕ 1 TO BEFORE 2 1) 

ар 

((МАРС ҒООҒМ5 %) "<с.г.>") 


By simply converting the input from two expressions to one expression, the desired effect, that of 
mapping down the list that was the value of foofns, was achieved, Қ 


REDO, USE, and FIX all operate by obtaining the input portion of the corresponding event, 
processing the input (except for REDO), and then storing it on the history list as the input portion 
of a new event. The history command completes operating by simply unreading the input. When 
the input is subsequently "reread", the event which already contains the input will be retrieved and 
used for recording the value of the operation, saving side-effects, etc., instead of creating a new 
event. Otherwise the input is treated exactly the same as if it had been typed in directly. 


If ¢ specifies more than one event, the inputs for the corresponding events are simply concatenated 
into a linear sequence, with special markers (called pseudo-carriage returns) representing carriage 
returns? inserted between each input to indicate where new lines start. The result of this 


21 For inputs in eval format, i.e., single expressions, FIX calls the editor so that the current expression is that input, 
rather than the list consisting of that input - see the example on the preceding page. However, the entire list is 
actually being edited. Thus if the user typed 7 P in that example, he would see ((DEFINEQ FOO 8) "<с.г.>"). 

2 +. с.г. >" denotes а pseudo-carriage return and is explained later. 

23 The value of the variable histstrü is used to represent a carriage return. For readability, this value is the string 


"Сето". Note that since the comparison is made using са, this marker will never be confused with a Po that 
was урей in by the user. | 
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concatenation is then treated as the input referred to by ¢. For example, when the user typed 

REDO FROM Е ([7] on page 22.2) the inputs Юг the corresponding six events were concatenated to 

produce: | О 

(Е PUTD "<с.г.›" " МОМО) "<с.г.>" 3 "<с.г.>" (XTR 2) "<с.г.>" 

0 "<c.r.>" (SW 2 3)). Similarly, if the user “| Пад typed 

. USE PUTD FOR ФОТО IN 15 THRU 20, the above list would have been constructed, and then 
. PUTD substituted for GUTD throughout it. 


The same convention is used for representing multiple inputs when a USE command involves. 

Sequential substitutions. For example, if the user types GETD(FOO) and then 

. USE ЕТЕ FUM FOR ЕОО, the input sequence that will Бе constructed is. 
(GETD (ЕТЕ) "<c.r.>" GETD (FUM)), which is the result of substituting ЕТЕ for FOO in 
(СЕТО (FOO) ) concatenated with the result of substituting РИМ for FOO іп (СЕТО (ЕОО)). | 


Once such a multiple input is constructed, it is treated exactly the same as a single input, i.e, ће 
input sequence is recorded in a new event, and then unread, exactly as described above. When the 

inputs are “reread,” the "pseudo-carriage-returns" are treated by lispxread and readline exactly as | 
real carriage returns, ie. they serve to distinguish between apply and eval formats on inputs to 
lispx, and to delimit line commands to the editor. Note that once this multiple input has been 
entered as the input portion of a new event, that event can be treated exactly the same as one 
resulting from type in. In other words, no special checks have to be made when referencing an 
event, to see if it is simple or multiple. Thus, when the user types REDO following 
REDO FROM F, ({10] page 22.3) REDO does not even notice that the input retrieved from the 
previous event is (Е PUTD "<c.r.>" ... (SW 2 3)) ie, a multiple input, it simply records 
this input and unreads it. Similarly, when the user then types USE GUTD FOR PUTD on this 
multiple input, the USE command simply carries out the substitution, and the result is the same аз | 

| though the user had typed USE QUTD FOR PUTD IN 15 THRU 20. | 


In sum, this implementation permits € to mer to a single simple event, or to several events, or to P 
. asingle event originally constructed from several events (which may themselves have been паре | 
input events, с) without having to treat each case separately. | 


-= HISTORY COMMANDS APPLIED TO HISTORY COMMANDS 


Since history commands themselves do not appear in the input portion of events (although they are 
Stored elsewhere in the event), they do not interfere with or affect the searching operations of event 
specifications. In effect, history commands are invisible to event specifications. 24 AS a result, 
history commands themselves cannot be recovered for execution in the normal way. For example, 
if the user types USE A В С FOR D and follows this with USE E FOR Р, he will not produce 


.. the effect of USE A B C FOR E (but instead will simply cause E to be substituted for D in Фе 


last event containing а D). To produce this effect, іе. USE A B С FOR E, the user should type 
USE D FOR E IN USE. The appearance of the word REDO, USE or FIX in an event address 
. specifies a search for the corresponding history command. (For example, the user сап also type 

UNDO REDO.) It also specifies that the text of the history command itself be treated as though it 
меге the input. However, the user must remember that the context in which a history command is 
reexecuted is that of the current history, not the original context. For example, if the user types 


JA USE FOO FOR FIE IN -1, and then later types REDO USE, the -1 will refer to the event 


AM 


ч before the REDO, not before the USE. 


With the exception described below under “History Commands that Fail”, 
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HISTORY COMMANDS THAT FAIL 


The one exception to the statement that “history commands are invisible to event specifications" 
occurs when a history command fails to produce any input. For example, suppose the user types 
USE LOG FOR ANTILOG AND ANTILOG FOR LOGG, causing lispx to respond LOGG ?. Since 
the USE ‘command did not produce any input, the user can repair it by typing 
USE LOG FOR LOGG (е. does not have to specify IN USE). This latter USE command will - 
invoke a search for LOGG, which will find the bad USE command. lispx then performs the 
indicated substitution, and unreads USE LOG FOR ANTILOG AND ANTILOG FOR LOG. In turn, 
this USE command invokes a search for ANTILOG, which, because it was not typed in but reread, 
ignores the bad USE command which was found by the earlier search for 1066, and which is still 
on the history list. In other words, history commands that fail to produce input are visible to 
searches arising from event specifications typed in by the user, but not to secondary event 
specifications. 


In addition, if the most recent event is a history command which failed to produce input, a 
secondary event specification will effectively back up the history list one event so that relative event 
numbers for that event specification will not count the bad history command. For example, 
suppose the user types USE LOG FOR ANTILOG AND ANTILOG FOR LOGG IN -2 AND -1, 
and after lispx types 1066 ?, the user types USE LOG FOR 1066. He thus causes the command 
USE LOG FOR ANTILOG AND ANTILOG FOR LOG IN -2 AND -1 to be constructed and 
unread. In the normal case, -1 would refer to the last event, i.e., the "bad" USE command, and -2 
to the event before it. However, in this case, -1 refers to the event before the bad USE command, 
and the -2 to the event before that. In short, the caveat that "the user must remember that the 
context in which a history command is reexecuted is that of the current history, not the original 
context" does not apply if the correction is performed immediately. | 


MORE HISTORY COMMANDS 

RETRY ¢ similar to REDO except sets helpclock so that any errors that occur 
while executing ¢ will cause breaks. 

.. Vars similar to USE except substitutes for the (first) operand. 

For example, EXPRP( FOO) followed by ... ЕТЕ FUM is equivalent to USE FIE FUM FOR FOO. 


See also event 52 on page 22.8. 


22% prints history list. If € is omitted, ?? prints the entire history list, 
beginning with most recent events. Otherwise ?? prints only those 
events specified in € (and in the order specified), e.g., ?? -1, ?? 10 
THRU 15, etc. | 


22 commands аге not entered оп the history list, and so do not affect relative event numbers. Іп 
other words, an event specification of -1 typed following а ?? command will refer to the event. 
immediately preceding the 7? command. | 


?? will print the history command, if any, associated with each event as shown at [9] оп page 22.3 
and page 22.6. Note that these history commands are not preceded by prompt characters, 
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indicating they are not stored as input. 


279 prints multiple input events under one event number (see page 22.6). 


Since events are initially stored on the history list with their value ficld equal to bell (control-G), if | 
an operation fails to complete for any reason, e.g., causes an error, is aborted, etc., its "value" will 
be ре This is the explanation for the blank line in event 2, page 22.6, and event 50, page 22.8. 


+ 2? resets the value of the variable it (see page 22.26) to be the value of the last event printed. 


** 


29 is implemented via the function printhistory, page 22.44, which can also be called directly by | 
the user. Printing is performed via the function showprind Ca 14), so that if the value of 
Sysprettyflg = T, events will be prettyprinted. 


.UN DO ¢ undoes the side effects of the specified events. For each event 


undone, UNDO prints a message: ер. 
RPLACA UNDONE, REDO UNDONE etc. If nothing is undone 
because nothing was saved, UNDO types NOTHING SAVED. If 
nothing was undone because the event(s) were already undone, 
. UNDO types ALREADY UNDONE. If ¢ is empty, UNDO searches back 
. for the last event that contained side effects, was not undone, and | 
кеп was not ап UNDO command. 


UNDO Ф: ху... Xp Each x; refers to a message printed by DWIM in the event(s) 


2 


2 


specified by €. The side effects of the corresponding РУМ | 
corrections, and only those side effects, are undone. 


REDO, RETRY, USE, ..., and FIX commands, i.e., those commands that reexecute previous events, are not stored 
as inputs, because the input portion for these events are the expressions to be “reread”. The history commands 
UNDO, NAME, RETRIEVE, BEFORE, and AFTER are recorded as inputs, and ?? prints them exactly as they were 


typed. 


Note that the user can undo UNDO commands themselves by specifying the conesponding event address, e.g., 
UNDO -7 or UNDO UNDO. 


. UNDOing events in the reverse order from which they were executed is guaranteed to restore all pointers correctly, 


e.g., to undo all effects of last five events, perform UNDO THRU -5, not UNDO FROM -5. Undoing out of order 
may һауе unforseen effects if the operations аге dependent. For example, if the user performed 
(NCONC1 FOO FIE), followed by (NCONC1 FOO FUM), and then undoes the (NCONC1 FOO ЕТЕ), he will also. 
have undone the (NCONC1 FOO FUM). If he then undocs the (NCONC1 FOO FUM), he will cause the FIE to 


reappear, by virtue of restoring FOO to its state before the execution of (NCONC1 FOO FUM). For more details, see 


page 22.33. 
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For example, if the message PRINTT [IN FOO] -> PRINT were рше UNDO : PRINTT or 
UNDO : PRINT would undo Ше correction.”8 | 


$29 is a special form of the USE command for conveniently specifying character substitutions. In 
addition, it has a number of useful properties in connection with events that involve errors. 


$x FORy IN¢ equivalent to USE $x$ FOR $y$ IN ¢ 


For example, the user types MOVD(FOO FOOSAVE T), he can then type $ ЕТЕ FOR FOO IN 
MOVD to perform MOVD(FIE FIESAVE T). Note that USE FIE FOR FOO would pon 
MOVD(FIE FOOSAVE T). 


An abbreviated form of $ is available: 


фух ТМ Ф same as $x FOR y IN €, ie. уз are changed to x’s. can also бе 
written аз $ у TOx,$y =x,or$y->x. 


$ does event location the same as the USE command, i.e., if IN € is not specified, $ searches for 
y. 


After $ finds the event, it looks to see if an error was involved in that event, and if the indicated 
character substitution can be performed in the object of the error message, called the offender.?! If 
50, $ assumes the substitution refers to the offender, performs the indicated character substitution 
in the offender only, and then substitutes the result for the original offender throughout the event. 
For example, the user types (PRETTYDEF FOOFNS 'FOO FOOOVARS) causing а 
U.B.A. FOOOVARS error message. The user can now type $ OO O, which will change 
FOOOVARS to FOOVARS, but rot change FOOFNS or FOO. 


If an error did occur in the specified event, the user can also omit specifying the object of the 
substitution, y, in which case the offender itself is used. Thus, the user could have corrected the 
above example by simply typing $ FOOVARS. Since esubst is used for performing the 
substitution, і.е. the editors R command (see Section 9), $ сап be used in x to refer to Һе - 
characters in y. For example, if the user types LOAD(PRSTRUC PROP), causing the error 
FILE NOT FOUND PRSTRUC, he can request the file to be loaded from LISP's directory by 
simply typing $ <LISP>$. This is cquivalent to performing (В PRSTRUC <LISP>$) on the 
event, and therefore replaces PRSTRUC by <LISP>PRSTRUC. 


28 Some portions of the messages printed by DWIM are strings, e.g., the message FOO UNSAVED is printed by printing 
FOO and then " UNSAVED". Therefore, if the user types UNDO : UNSAVED, the DWIM correction will not be 
found. He should instead type UNDO : FOO or UNDO : SUNSAVEDS ( < esc > UNSAVED< esc >, see R command in 
editor, Section 9). | 

2 $ is Ше way that <esc> is echoed іп Interlisp-10. Rather than writing <esc> throughout in the discussion Ша! 
follows, $ is used instead, since this is what the user will see when he types < esc». 

30 However, unlike USE, $ can only be used to specify one substitution at a time. 

31 


Whenever an error occurs, the offender is automatically saved on that event's entry in the history list, under the 
property *ERROR*, | 
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Note that $ also works for events in the editor. For example, if the user types 
(MOVE COND 33 2 TO BEFORE HERE), and the editor types 337, the user can type 5 3, 
causing 3 to be substituted for 33 in the MOVE command. 


Note also that $ never searches for an error. Thus, if the user types LOAD(PRSTRUC PROP) 
causing а FILE МОТ FOUND error, types CLOSEALL(), and then types $ <LISP>$, lispx will 
complain that there is no error in CLOSEALL(). In this case, the user would have to type 
$ <LISP>$ IN LOAD, or $ PRS <LISP>PRS (which would cause a search for PRS). 


Note also that $ operates on input, not on programs. If the user types ҒОО(), and within the call 
to FOO gets a U.D.F. CONDD error, he cannot repair this by $ COND. lispx will type 
CONDD NOT FOUND IN FOO(). | 


DWIM € this command is an instruction to the programmer's assistnat to 
reexecute the indicated event, only to "try harder" as described 
below. 


The basic idea behind the DWIM command is that the user has typed something that (a) is not what 
he meant to type, and (b) he feels that the p.a. has sufficient information to infer what it was that 
he did mean to type. For example, suppose the user had typed GETP(FOO MACCRO), which 
returned NIL. There is no "error" in this event: it is perfectly reasonable for getp to be given as its 
second argument a property not on the property list of a particular atom, or in fact, a property not 
on the property list of any atom. Thus there is no justification for DWIM or the programmer's 
assistant to perform any corrections or transformations in this event. Nevertheless, most users 
would recognize that what was meant was GETP(FOO MACRO). Thus if the user types 
DWIM GETP (or just DWIM if the GETP was the previous event), the p.a. would correct MACCRO to 
MACRO and reexecute the event. 


Another example is if the user types SET(INITIALLS RMK:), which performs the indicated 
assignment, and returns RMK:. This sets the value of the new, previously unbound variable initialls, - 
whereas the user intended to set the time stamp package parameter, initials (see Section 9). The 
user now types DWIM, the programmer's assistant undoes the indicated event, corrects. INITIALLS 
to INITIALS, and then reexecutes the event. 


The DWIM command is implemented by associating with various functions certain declarative 
information about their arguments, e.g. for getp, the p.a. knows that atm, its first. argument, 
"should" have a non-NIL property list, and prop, its second argument, either should be one of the 
property names on that property list, or else a member of sysprops. When the p.a. is given a DWIM 
command, it searches the indicated event looking for a function for which one of these declarations 
is not зацобед.32 It then tries to "coerce" the corresponding argument so that the declaration is 
true, e.g. if told that the argument should have a property list, the p.a. would attempt spelling | 
correction using the spelling lists userwords, spellings2, апа  spellingsl, specifying 

fn=GETPROPLIST. | | 


The р.а. currently knows about the following information in the context of the DWIM command: 


(1) getd, fntyp, and movd should be given as a first argument an atom which has a definition; 


32 looking at quoted arguments only, e.g. if the user types (GETP X 'MACCRO), Ше ра. would not try to do anything 


to X (or its value). The DWIM command works only on what is typed by the user. 
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(2) getp, getprop, getproplist, put, and putprop should given as a first argument an atom which has 
а non-NIL property list, and as a second argument, a property which is either on the property list 
. of that atom, or a member of sysprops; 

(3) set, setq, and sctqq should be given a variable that has а top level value ог is bound; 

(4) loadfns and editf should be given the name of a function that is contained on one of the files 
on filelst. 


When the DWIM command is typed, and any of these conditions are not true, and the 
programmer's assistant can make them be true by appropriate spelling correction(s), the corrected 
event will be reexecuted. Otherwise, if all declarations are satisfied or the p.a. is unable to coerce 
an argument to satisfy one of these conditions, there is still one more thing that it can try: if an 
error occurred in the indicated event, the p.a. will pack $$ (two <esc>s) on the end of the 
offender, substitute the result for the offender throughout the event, and then reexecute the event. 
For those events in which the editor's pattern match is being employed (see Section 9), e.g. history 
commands, edit commands, etc., this has the effect of specifying a search for an atom that is 
"close" to the offender in the sense used by the spelling corrector (see pattern type 6b, Section 9). 
For example, suppose the user types UNDO LOADD, to which the p.a. responds LOADD ? because 
there was no event on the history list containing the atom LOADD. The user then types DWIM, and 
the p.a. is able to find an event containing LOAD. Similarly, the user types to the editor 
(MOVE 3 2 TO AFTER CONDD 1), and gets the error message CONDD? because the find 
command failed to find CONDD. A DWIM command will cause the edit command 
(MOVE 3 2 TO AFTER CONDD$$ 1) to be executed, which will search for an atom that is 
"close" to CONDD, e.g. COND. 


If all of these procedures fail, the p.a. types "Unable to figure out what you meant 


in:" followed by the indicated event. 


NAME atom € saves the event(s) (including side effects) specified by ¢ on the 
property list of atom (under the property HISTORY) eg. 
NAME FOO 10 THRU 15. NAME commands are undoable. 


Commands defined by NAME can also be typed in ome as though they were built-in T 
e.g., FOO? is equivalent to REDO F00.? 


Commands defined by NAME can also be parameterized, i.e., be defined to take arguments: 


NAME name (args) : € args are interpreted the same as the arguments 
Or for a USE command. See page 22.13. When name _ 
NAME пате ... args... : € is invoked, the argument values are substituted for args using the 


same substitution algorithm as for USE. 


For example, following the event (PUTD 'FOO (COPY (GETP 'FIE 'EXPR))), the user types 
МАМЕ MOVE FOO ЕТЕ : PUTD. Then typing MOVE TEST1 TEST2 would cause 
(PUTD 'TEST1 (COPY (GETP 'TEST2 'EXPR))) to be executed, i.e., would be equivalent to 
typing USE TEST1 TEST2 FOR ЕОО ЕТЕ IN MOVE. Typing MOVE A B C D would cause two 
PUTD's to be executed. Note that "5 and $'s can also be employed the same as with USE. For 
example, if following 


33 


However, if FOO is the name of a variable, it would be evaluated, i.e., F002 would return the value of FOO. 
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«РКЕРІМПЕХ( <MANUAL>14LISP.XGP) 

«FIXFILE( <MANUAL>14LISP.XGPIDX) 
the user performed NAME FOO 5145 : -2 AND -1, then FOO $15$ would perform the 
indicated two operations with 14 replaced by 15.34 


RETRIEVE atom Retrieves and reenters on the history list the events named by 
atom. Causes an error if atom was not named by a NAME 
command. 


For example, if the user performs NAME FOO 10 THRU 15, and at some time later types 
RETRIEVE FOO, 6 new events will be recorded on the history list (whether or not the 


- corresponding events have been forgotten yet). Note that RETRIEVE does по! reexecute the 
events, it simply retrieves them. The user can then REDO, UNDO, FIX, etc. any or all of these 


events. Note that the user can combine the effects of a RETRIEVE and a subsequent history 
command in a single operation, e.g., REDO FOO is equivalent to RETRIEVE FOO, followed by an 
appropriate REDO.?? Note that UNDO FOO and ?? FOO are permitted. 


BEFORE atom undoes the effects of the events named by atom. 
AFTER atom undoes a BEFORE atom. 


BEFORE/AFTER provide a convenient way of flipping back and forth between two states, namely 
that state before a specified event or events were executed, and that state after execution. For 
example, if the user has a complex data structure which he wants to be able to interrogate before 
and after certain modifications, he can execute the modifications, name the corresponding events 
with the NAME command, and then can turn these modifications off and on via BEFORE or AFTER 


. commands. Both BEFORE and AFTER are no-ops if the atom was already in the corresponding 
State; both generate errors if atom was not named by a NAME Е command. | 


Note: since UNDO, NAME, RETRIEVE, BEFORE, and AFTER are recorded as inputs they can be 
referenced by REDO, USE, etc. in the normal way. However, the user must again remember that 
the context in which the command is reexecuted is different than the original context. For 
example, if the user types NAME FOO DEFINEQ THRU COMPILE, then types ... FIE, the input 
that will be reread will be NAME FIE DEFINEQ THRU COMPILE as was intended, but both 
DEFINEQ and COMPILE, will refer to the most recent event containing those atoms, namely the 
event consisting of NAME FOO DEFINEQ THRU COMPILE! 


34 NAME FOO € is equivalent to NAME FOO : €. In either case, if FOO is invoked with arguments, ап error is 
generated. Чч 


35 Actually, REDO FOO is better than RETRIEVE followed by REDO since іп the latter case, the corresponding events 
would be entered on the history list twice, once for the RETRIEVE and once for the REDO. 


36 The alternative to BEFORE/AFTER for repeated switching back and forth involves UNDO, UNDO of the 
UNDO, UNDO of that etc. At cach stage, the user would have to locate the correct event to undo, and furthermore _ 
would run the risk of that event being "forgotten" if he did not switch at Icast once per time-slice. 
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ARCHIVE ¢ records the events specified by ¢ on a permanent history list. This 
history list can be referenced by preceding a standard event 
specification with @@, e.g., ?? @@ prints the archived history list, 
REDO @@ -1 will recover the corresponding event from the 
archived history list and redo it, etc. 


The user can also provide for automatic archiving of selected events by appropriately defining 
archivefn, or by putting the property *ARCHIVE*, value T, on the event. Events that are 
referenced by history commands are automatically marked for archiving in this fashion. For more 
details, see page 22.28. 


FORGET € permanently erases the record of the side effects for the events 
specified by €. If € is omitted, forgets side effects for entire history 
list. 


FORGET is provided for users with space problems. For example, if the user has just performed 
sets, rplacas, rplacds, putd, remprops, etc. to release storage, the old pointers would not be garbage 
collected until the corresponding events age sufficiently to drop off the end of the history list and 
be forgotten. FORGET can be used to force immediate forgetting (of the side-effects only). 
FORGET is not undoable (obviously). 


REMEMBER € instructs the file package to "remember" the events specified by ќ. 
These events will be marked as changed objects of file package type 
EXPRESSIONS! For example, following: | 


-MOVD?(DELFILE /DELFILE) 

DELFILE 

-REMEMBER -1 

(MOVD? (QUOTE DELFILE) (QUOTE /DELFILE)) 


if the user calls Ве, «| makefiles, or cleanup, the command 
(P (MOVD? (QUOTE DELFILE) (QUOTE /DELFILE))) will be constructed by the file 
package and added to the fileCOMS indicated by the user. 3 


22.5 MISCELLANEOUS FEATURES AND COMMANDS 


PL atom (property list) prints out the property list of atom in a nice format, 
with printlevel reset to (2 . 3), e.g. 


ері + 


37 which can be written out via the file package command P 


38 unless the user has already explicitly added the corresponding expression to some P command himself. Note that 
"remembering" ап event like PUT(FOO CLISPTYPE expression) will лог result іп а 
(PROP CLISPTYPE FOO) command, because this will save the current (at the time of the makefile) value for the 
CLISPTYPE property, which may or may not be expression. Thus, even if there is a PROP command which saves 
the CLISPTYPE property for FOO in some fileCOMS, remembering this event will still require a 
(P (PUT 'FOO 'CLISPTYPE 'expression)) command to appear. 
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CLISPTYPE: 12 
ACCESSFNS: (PLUS IPLUS FPLUS)?? 


PB atom | | (print bindings) prints value of atom with printlevel reset to (2 . 3). 
| If atom is not bound, does not attempt spelling correction or 
generate an error. 


? $ For use following an error. If € is not specified, searches back on 
| history list for last event that contains an error. The programmer's . 
assistant then attempts to "analyze" the nature and cause of the 
error using the context information that was automatically saved at 

the time of the error. 


For example, suppose the function foo contains the expression (ELT-X 3), and foo is called with 


х equal to (4526234), i.e., a list of an array, causing the error ARG NOT ARRAY. ТЕ the user then 


types 7, the programmer's assistant will respond with: 


because elt requires that A (its first argument) be an array, but in 
(ELT X 3) {in FOO}, the value of X is (#526234) 


The programmer’s assistant contains built-in information about many of the more common еггог5, 1 
In the event that it is unable to analyze the error, the ргоргаттег 5 assistant simply calls helpsys 
(Section 20) to present the user with information from the Interlisp manual cere: to this error 
message. 


allows the user to type a line of text without having the 
| programmer’s assistant process it. Useful when linked to other 
users, Or to annotate a dribble file (Section 21). 


EXEC Я | -~ jn Interlisp-10, calls subsys (Section 21) to descend to lower ехес,42 

9 pL is implemented via the function printprops. 

40 PB is also a break command (Section 15). As a break command, it ascends the stack, and, for each frame in which 
atom is bound, prints the frame name and value of atom. If typed in to Ше programmer's assistant when not at the 
top level, e.g. in the editor, a lower userexec, etc., PB will also ascend the stack as it does with a break. However, as 
a programmer’s assistant command, it is primarily used to examine the top level value of a variable that may or may 
not be bound, or to examine a variable whose value is a large S-expression. PB is implemented via the function . 
printbindings. | 

^l At some point in the future, we hope to extend this facility to enable the programmer's assistant to propose | 
corrections to certain simple errors, e.g., argument reversal, leaving out an argument, etc. 

42 Rather than start up a new fork each time the user types EXEC, the EXEC command will save the old fork handle 


upon return from an EXEC command, and, if the fork handle is still active, reuse it for the next EXEC command, i.e. 
an EXEC followed by another EXEC is equivalent to an EXEC followed by a CONTIN. 
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CONTIN in Interlisp-10, performs subsys{T] (see Section 21) to continue last 
call to subsys. | 


TYPE-AHEAD is a command that allows the user to type-ahead an indefinite 
number of inputs. 


The assistant responds to TYPE-AHEAD with a prompt character of >. The user can now type in 
an indefinite number of lines of input, under errorset protection. The input lines are saved and 
unread when the user exits the type-ahead loop with the command 500 (< esc > GO). While in the | 
type-ahead loop, ?? can be used to print the type-ahead, FIX to edit the type-ahead, and $Q 
(< esc > 0) to erase the last input (may be used repeatedly). For example: | 


©TYPE-AHEAD 

>SYSOUT (ТЕМ) 
>MAKEFILE(EDIT) 
>BRECOMPILE( (EDIT WEDIT)) 


>$Q 

\\BRECOMPILE 

>LOAD(WEDIT PROP) 

>BRECOMPILE((EDIT WEDIT)) - 

>F 

>MAKEFILE( BREAK) 

>LISTFILES(EDIT BREAK) 

>SYSOUT (CURRENT) 

»LOGOUT] 

»?? 
»SYSOUT(TEM) 
»MAKEFILE(EDIT) 
>LOAD(WEDIT PROP) 
>BRECOMPILE( (EDIT WEDIT)) 
>F 
>MAKEFILE( BREAK) 
>LISTFILES(EDIT BREAK) 
>SYSOUT (CURRENT) 
»LOGOUT] 

>FIX 

EDIT 

*(R BRECOMPILE BCOMPL) 

«p 


((LOGOUT) (SYSOUT &) (LISTFILES &) (MAKEFILE &) (F) (BCOMPL &) 
(LOAD &) (MAKEFILE &) (SYSOUT &)) 

*(DELETE LOAD) 

“ОК 

2500 


The TYPE-AHEAD command may be aborted Бу $5ТОР (< esc > STOP); contol E йу aborts 
the current line of input. 


43 


Note that type-ahcad can be addressed to the compiler, since it uses lispxread for input. Type-ahead can also be 
directed to the editor, but type-ahead to the editor and to lispx cannot be intermixed. 
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· $BUFS (X esc > BUFS) is a command for recovering the input buffers. 


Whenever an error occurs in executing a lispx input or edit command, or a control-E or control-D 
is typed, the input buffers are saved and cleared. The $BUFS command is used to restore the 


input buffers, i.e., its effect is exactly the same as though the user had retyped what was "lost." For 


example: 


*(-2 (SETQ X (COND ((NULL Z) (CONS (user typed control-E) 
жр 

(COND (& 8) (T &)) 

*2 


*$BUFS 
(-2 (5ЕТ0 X (COND ((NULL Z) (CONS 


and user can now finish typing the (-2 ..) command. 


Note: the type-ahead does not have to have been seen by Interlisp, i.e., echoed, since the system 
buffer is also saved. 


Input buffers are not saved on the history list, but on a free variable. Thus, only the contents. of 
the input buffer as of the last clearbuf can ever be recovered. However, input buffers cleared at 
evalqt are saved independently from those cleared by break or the editor. The procedure followed 
when the user types $BUFS is to recover first from the local buffer, otherwise from the top level | 
buffer./^' Thus the user can lose input in the editor, go back to evalgt, lose input there, then go 


back into the editor, recover the editor's buffer, etc. Furthermore, a buffer cleared at the top can _ | 
be recovered in a break, and vice versa. 


valueof[x] mí is an nlambda function for obtaining the value of a particular event, 
e.g, (VALUEOF -1),9 (VALUEOF «FOO -2). 


The value of an event consisting of several operations is a list of the 
values for each of the individual operations. 


Note: the value field of a history entry is initialized to bell (control-G). Thus a value of bell 
indicates that the corresponding operation did not complete, ie, was aborted or caused an error (or — 
else returned bell). 


IT | "n the value of it is always the value of the last event executed, i.e. 
valueof[-1], e.g. 


44 тре local buffer is stored on lispxbufs; the top level buffer on toplispxbufs. The forms of both buffers are 
(CONS (LINBUF) (SYSBUF)) (see Section 14). Recovery of a buffer is destructive, ie. ФВЏЕ5 sets the 
corresponding variable to NIL. If the user types $BUFS when both lispxbufs and toplispxbufs are NIL, the message 
NOTHING SAVED is typed, and an error generated. 


45 Although the input for valucof is entered on the history list before valucof is called, valucof[-1] still refers to the 
value of the expression immediately before the valueof input, because valucof effectively backs the history list up one 
entry when it retrieves the specified event. Similarly, (VALUEOF FOO) will find the first event before this one that 
contains a Ғ00. 
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«(SORT 2) 
1.414214 
«(SORT IT) 
1.189207 


If last event was a multiple event, e.g. REDO -3 THRU -1, it is set | 


to value of the last of these events. Folowing a ?? command, it is 
set to value of corresponding event. In other words, in all cases, it 
is set to the last value printed on the terminal. 


control-U*® when typed in at any point during an input being read Бу 


lispxread, permits the user to edit the input before it is returned to 
the calling function. 


This feature is useful for correcting mistakes noticed in typing’ before the input is executed, instead 
of waiting till after execution and then performing an UNDO and a FIX. For example, if the user 
types (DEFINEQ (FOO (LAMBDA (X) (FIXSPELL X and at that point notices the missing left 
parenthesis, instead of completing the input and allowing the error to occur, and then fixing the 
input, he can simply type control-U,* finish typing normally, whereupon the editor is called on 
(FOO (LAMBDA (X) (FIXSPELL X -- ], which the user can then repair, e.g., by typing 
(LI 1). If the user exits from the editor via OK, the (corrected) expression will be returned to 
whoever called lispxread exactly as though it had been (уред 38 If the user exits ма STOP, the 
expression is returned so that it can be stored on the history list. However it will not be executed. 


In other words, the effect is the same as кі the user had ORs control-E at exactly the right 


instant. 

prompt Пе is a flag which when set to T causes the current event number to be | 
printed before each е, : and * prompt characters. See description 
of promptchar, page 22.38. 
prompt # Пр is initially NIL. 

promptcharforms list of forms to be executed each time promptchar is called. бее 


description of promptchar. 


promptcharforms initially contains the expression (CHECKNIL) which checks to see if car or cdr of | 


NIL have been clobbered, or NIL or T have been reset or rebound, and if so, restores them and 
prints a warning message. 


historysaveforms list of forms to be executed each time historysave is called. See 
description of historysave. 


46 control-N for Interlisp on TOPS-20, 


Control-U can be typed at any point, even in the middle of an atom; it simply sets a variable checked by lispxread. 


48 


Control-U also works for calls to readline, i.e., for line commands, 
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Note that promptcharforms and historysaveforms together enable bracketing each interaction with 
the user, e.g. to measure how long he takes to respond, use a different readtable or terminal table, 
etc. 


resetforms | list of forms to be evaluated at each RESET, i.e. when user types 
control-D, calls function reset, or types control-C followed by 
START. 

archivefn | allows the user to specify events to be automatically archived. 


When archivefn is set to T, and an event is about to drop off the end of the history list and be 


forgotten, archivefn is called giving it as its first argument the input portion of the event, and as its 
second argument, the entire event. A? If archivefn returns T, the event is archived. For example, 
some users like to Кер а record of ай calls to load. Defining archivefn as: 
(LAMBDA (X Y) (EQ (CAR X) (QUOTE LOAD))) will accomplish this. Note that archivefn 
must be both set and defined. archivefn is initially NIL and undefined. 


The user can also specify that a particular event be archived when it is about to drop off the end 
of the history list by putting the property *ARCHIVE*, value T, on the event, e.g., by means of an 
appropriately defined lispxuserfn (see below) Оле use of this feature is that the system 
automatically adds the *ARCHIVE* property to all events that are referenced by history 
commands.?? Thus once an event is redone, it is guaranteed to be saved. 


lispxmacros provides a macro facility for lispx. 


_ lispxmacros allows the user to define his own lispx commands. It is a list of elements of the form 


(command def). Whenever command appears as the first expression on a line in a lispx input, the 


variable lispxline is bound to the rest of the line, the event is recorded on the history list, and def 


is evaluated, and its value stored as the value of the event. Similarly, whenever command appears 
as car of a form in a lispx input, the variable lispxline is bound to cdr of the form, the event | 
recorded, and def is evaluated?! (See page 2244 for an example of a lispxmacro). RETRIEVE, 
BEFORE, and AFTER are implemented as lispxmacros. In addition in Interlisp-10, LISP, 
SNDMSG, TECO, and EXEC are lispxmacros which perform the corresponding calls to subsys 
(Section 21), and CONTIN is a lispxmacro which performs (SUBSYS T). SY is a lispxmacro which 
performs the SYSTAT command. Finally, DIR is a lispxmacro which calls the function directory, 
e.g, DIR *.COM; * lists all compiled files. (For more details, see Section 21.) 


lispxhistorymacros provides a macro facility for history commands. 


lispxhistorymacros allows the user to define his own history commands. Тһе format of 


49 In case archivefn needs to examine the value of the event, its side effects, etc. See page 22.34 for discussion of the 
format of history lists. 

50 — unless archiveflg - NIL. archiveflg is initially T. 

51 


An element of the form (command NIL def) is interpreted to mean bind lispxline and evaluate def as described 
above, except do пог save the event on the history list. | 
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lispxhistorymacros is the same as that of олоо. except that the result of evaluating def is 
treated as a list of expressions to be unread, exactly as though the expressions had been retrieved 


by a REDO command, or computed by a USE command.° Note that returning NIL means nothing 


else is done. This provides a mechanism for defining lispx commands: which are executed for 
effect only, and do not really have values, per se. For example, the ? command is арша as 


a lispxhistorymacro. 


lispxuserfn provides a way for a user function to process selected inputs. 


When lispxuserfn is set to T, it is applied?? to all inputs not recognized as one of the commands 
described above. If lispxuserfn decides to handle this input, it simply processes it (the event was 
already stored on the history list before lispxuserfn was called), sets lispxvalue to the value for the 
event, and returns T. lispx will then know not to call eval or apply, and will simply store 
lispxvalue into the value slot for the event, and print it. If lispxuserfn returns NIL, lispx proceeds 
by calling eval or apply in the usual way. Thus by appropriately defining (and setting) lispxuserfn, 
the user can with a minimum of effort incorporate the features of the programmer's assistant into 
his own executive (actually it is the other way around). | 


The following output illustrates such а coupling.>4 


**SETQ(ALTFORM (MAPCONC NASDIC (РИС (GETP X 'ALTFORMS] | [1] 
=NASDICT 
(AL26 ВЕ7 С056 СО57 CO60 C13 НЗ MN54 МА22 5С46 534 Т144) 
**(GIVE ME LINES CONTAINING COBALT) | [2] 
SAMPLE PHASE  СОМЅТІТ. CONTENT UNIT CITATION TAG “| 
510002 OVERALL C056 40.0  DPM/KG 070-237 0 | 

C13 8.8 DEL D70-228 0 

H3 314.0 ПРМ/К6 

MN54 28 
**GETP(COBALT ALTFORMS) [3] 
(C055 C057 С060 C13 H3 МН54 NA22 SC46 534 1144) 
**UNDO MAPCONC [4] 
SETQ UNDONE. 
**REDO GETP | [5] 
(C056 С057 С060) 
**REDO COBALT | ге 
SAMPLE PHASE СОМЅТІТ. CONTENT UNIT CITATION TAG E 
510002 OVERALL C057 40.0 DPM/KG 070-237 0 
510003 OVERALL СО 15.0 070-203 0 

14,1 070-216 

с056 43.0 DPM/KG 070-237 0 

С057 43.0 070-241 0 

с060 1.0 | 


**USE MANGANESE FOR COBALT 


52 See page 22.15 for discussion of implementation of REDO, USE, and FIX. 
53 Like archivefn, lispxuserfn must be both set and defined, 
54 


The output is from the Lunar Sciences Natural Language Information System devcloped for the NASA Manned 
Spacecraft Center by William A. Woods of Bolt Beranek and Newman Inc., Cambridge, Mass, 
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Section 22: The Programmer's Assistant 


The user is running under his own executive program which accepts requests in the form of 


sentences, which it first parses and then executes. The user first "innocently" computes a list of all 
ALTERNATIVE-FORMS for the elements in his system [1]. He then inputs a request in sentence 
format [2] expecting to see under the column CONSTIT. only cobalt, CO, or its alternate forms, 
CO56, СО57, ог CO60. Secing СІЗ, НЗ, апа MN54, he aborts the output, and checks the 
property ALTFORMS for COBALT [3]. The appearance of C13, НЗ, MN54, he aborts the output, 
and checks the property ALTFORMS for COBALT [3]. The appearance of СІЗ, H3, MN54 et al, 
remind him that the mapconc is destructive, and that in the process of making a list of the 
ALTFORMS, he has inadvertently strung them all together. Recovering from this situation would 
require him to individually examine and correct the ALTFORMs for each element in his dictionary, 
a tedious process. Instead, he can simply UNDO MAPCONC, [4] check to make sure the 
ALTFORM has been corrected [5], then redo his original request [6] and continue. The UNDO is 
possible because the first input was executed by lispx; the (GIVE ME LINES CONTAINING 
COBALT) is possible because the user defined lispxuserfn appropriately; and the REDO and USE 


are possible because the 


(GIVE ME LINES CONTAINING COBALT) was stored оп the history list before it was 
transmitted to lispxuserfn and the user's parsing program. 


lispxuserfn is a function of two arguments, x and line, where x is the first expression dedi and 


ine the rest of the line, as read by readline (see page 22. 35). For example, if the user types 


ЕОО(А B C), х-Ғ00, and line-((A B C)); if the user types (FOO A B C), 
x=(FOO А B C), and line=NIL; and if the user types FOO A B C, х-Ғ00 and 
line- (A В С). AE | 


Thus in the above example, lispxuserfn would be defined as: 


[LAMBDA (X LINE) 
(COND “ 
( (AND (NULL LINE) 
(LISTP X)) 
(SETQ LISPXVALUE (PARSE ху) 


Т] 


Note that since lispxuserfn is called for each caput (except for р.а. commands), it can also be me 


to monitor some condition or gather statistics. 


In addition to saving inputs and values, lispx saves most system messages on the history list, e.g., 
FILE CREATED -- , (fn REDEFINED), (var RESET), output of TIME, BREAKDOWN, STORAGE, 
DWIM messages, etc. When printhistory prints the event, this output is replicated. This facility is 


implemented via the functions lispxprint, lispxprinl, lispxprin2, lispxspaces, lispxterpri, lispxtab, 


and lispxprintdef?? 56 In addition to performing the corresponding output operation, these 


35 ie. to perform output operations from user programs so that the output will appear on the history list, the program 
needs simply to call the corresponding lispx printing function. All of these functions have an optional argument, 
nodoflg, which if T, says to store the output on the history list as though it had been printed, but not to do the 
actual printing. | 

56 


The function userlispxprint is available to permit the user to define additional lispxprinting functions for already 
existing printing functions. The user can define a lispxprinting function by simply giving it the definition of 
userlispxprint, с.р., MOVD(USERLISPXPRINT LISPXPRINTDEF), as long as the new function name is formed by 
adding "LISPX" to the front of the name of an existing printing function, and that this function takes three or fewer 
arguments, and the second argument be the file name. uscrlispxprint is defined to look back on the stack, find the 
name of the calling function, strip off the leading "LISPX", perform the appropriate saving information, and then 
call the function to do the actual printing. 
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functions store ап appropriate expression on the history event under Ше property 
*LISPXPRINT*.>’ This expression is used by printhistory to reproduce the output. 


Lispx also performs spelling corrections using lispxcoms, a list of its commands, as a spelling list 
whenever и is given ап unbound atom or undefined function, 1.е., before ш, (0 evaluate 
the input? 


22.6 UNDOING 


The UNDO capability of the programmer’s assistant is implemented by requiring that each operation 
that is to be undoable be responsible itself for saving on the history list enough information to 
enable reversal of its side effects. In other words, the assistant does not "know" when it is about 
to perform a destructive operation, ie., it is not constantly checking or anticipating. Instead, it 
simply executes operations, and any undoable changes that occur are automatically saved on the 
history list by the responsible function.?? The operation of UNDOing, which involves recovering the 
saved information and performing the corresponding inverses, works the same way, so that the user 
can UNDO an UNDO, and UNDO that etc. 


At each point, until the user specifically requests an operation to be undone, the assistant does not 
know, or care, whether information has been saved to enable the undoing. Only when the user 
attempts to undo an operation does the assistant check to see whether any information has been 
saved. If none has been saved, and the user has specifically named the event he wants undone, the 
assistant types NOTHING SAVED. (When the user simply types UNDO, the assistant searches for the 
last undoable event, ingnoring events already undone as well as UNDO ОРС themselves, Ра 


This implementation minimizes the overhead for undoing. Only those operations which actually : 
make changes are affected, and the overhead is small: two or three cells of storage for saving the 
information, and an extra function call. However, even this small price may be too expensive if 
the operation is sufficiently primitive and repetitive, i.e., if the extra overhead may seriously 
degrade the overall performance of the ргоргат.60 Hence not every destructive operation in a 
program should necessarily be undoable; the programmer must be allowed to decide each case 
individually. | 


Therefore for each primitive destructive operation, we have implemented two separate functions, 
one which always saves information, 1.е., is always undoable, and one which does not, e.g., /rplaca 


57 unless lispxprintflg is NIL. 


58 lispx is also responsible for rebinding helpclock, used by breakcheck, Section 16, for computing the amount of time 


spent in a computation, in order to determine whether to go into a break if and when an error occurs. 


59 


When the number of changes that have been saved exceeds the value of #undosaves (initially set to 50), the user is 
asked if he wants to continue saving the undo information for this event. The purpose of this feature is to avoid 
tying up large quantities of storage for operations that will never need to be undone. The interaction is handled by 
the same routines used by DWIM, so that the input buffers are first saved and cleared, the message typed, then the 
system waits dwimwait seconds, and if there is no response, assumes the default answer, which in this case is NO. 
Finally the input buffers are restored. See page 22.41 for details. 


The rest of the discussion applies only to lispx; the editor handles undoing itself in a slightly different fashion, as 
described on page 22.45. 
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and rplaca, /remprop and remprop.®! In the various system packages, the appropriate function is 
used. For example, break uses /putd and /remprop so as to be undoable, and DWIM uses /rplaca 
and /rplacd, when it makes a correction.®* Similarly the user can simply use the corresponding / 
function if he wants to make a destructive operation in his own program undoable. When the / 
function is called, it will save the undo information in the current event on the history list. 


However, all operations that are typed in to lispx are made undoable, simply by substituting the 
corresponding undoable function for any destructive function throughout the input.®? For example, 
on page 227, when the user typed  (MAPCONC NASDIC (F/L ...)) it was 
(/MAPCONC NASDIC (F/L ...)) that was evaluated. Since the system cannot know whether 
efficiency and overhead are serious considerations for the execution of an expression in a user 
program, the user must decide, e.g., call /mapconc if he wants the operation undoable. However, 
expressions that are typed-in rarely involve iterations or lengthy computations directly. Therefore, | 
if all primitive destructive functions that are immediately contained in a type-in are made 
undoable, there will rarely be a significant loss of efficiency. Thus lispx scans all user input before 
evaluating it, and substitutes the corresponding undoable function for all primitive destructive - 
functions. Obviously with a more sophisticated analysis of both user input and user programs, the 
decision concerning which operations to make undoable could be better advised. However, we 
have found the configuration described here to be a very satisfactory one. The user pays a very 
small price for being able to undo what he types in, and if he wishes to protect himself from 


malfunctioning in his own programs, he сап have his program specifically call undoable functions, | 


or go into testmode as described next. 


TESTMODE 


Because of efficiency considerations, the user may not want certain functions undoable after his - 
program becomes operational However, while debugging he may find it desirable to protect 
himself against a program running wild, by making primitive destructive operations undoable. The 
function testmode provides this capability by temporarily making everything undoable. | 


testmode[flg] testmode[ T] redefines all primitive destructive functions with- 
their corresponding undoable versions and sets testmodeflg to T. 
testmode[] restores the original definitions, and sets testmodeflg to 
Мо. 


Note that setq’s are not undoable, even іп testmode. То make the corresponding operation 


· undoable in testmode, set or rplaca should be used. 


6l тһе "slash" functions that are currently implemented can be found as the value of /fns. 


62 The effects of the following functions are always undoable (regardless of whether or not they are typed in): define, 


———d"À 7 ——9À—À ES RR рл рашын шли сш. | 7 RENE 


eT пон ES RNS 7 | шшш оа —— У осе о о шеитецицањндв 7 penne 


readvise, plus апу changes caused by DWIM. 
63 Тһе substitution is performed by the function lispx/, described on page 22.42, 
ie., the "slash" functions; see footnote on page 22.32, 


65 testmode will have no effect on compiled mapconc's, since they compile open with frplacd’s. 
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UNDOING OUT OF ORDER 


_/тр1аса and /rplacd operate by saving the pointer that is to be changed and its original contents. 
(ie. /rplaca saves car and /rplacd saves cdr)  Undoing /rplaca and /rplacd simply restores the 
pointer. Thus, if the user types (RPLACA FOO 1), followed by (RPLACA FOO 2), then undoes 
both events by undoing the most recent event first, then undoing the older event, FOO will be 
restored to its state before either rplaca operated. However if the user undoes the first event, then 
the second event, (CAR ЕОО) will be 1, since this is what was in car of FOO before 
(RPLACA FOO 2) was executed. Similarly, if the user performs (NCONC1 FOO 1) then 
(NCONC1 ЕОО 2), undoing just (NCONC1 FOO 1) will remove both 1 and 2 from FOO. The 
problem in both cases is that the two operations are not "independent." In general, operations are 
always independent if they affect different lists or different sublists of the same 1151.60 Undoing in 
reverse order of execution, or undoing independent operations, is always guaranteed to do the 
"right" thing. However, undoing dependent operations out of order may not always have the 
predicted effect. 


SAVESET 


Setq's are made undoable on type in by substituting a call to saveset (described in detail on page 
22.40), whenever setq is the name of the function to be applied, or car of the form to be 


evaluated 67 In addition to saving enough information on the history list to enable undoing, saveset - 


operates in a manner analogous to savedef when it resets a top level value, i.e., when it changes а 
top level binding from a value other than NOBIND to a new value that is not equal to the old one. 
In this case, saveset saves the old value of the variable being set on the variable's property list 
under the property VALUE, and prints the message (variable RESET). The old value can be 
restored via the function unset,®8 which also saves the current value (but does not print a message). 
Thus unset can be used to flip back and forth between two values. 


град and града are implemented ма calls to saveset. Thus old values will be saved and messages 


printed for any variables that are reset as the result of loading а Ме. Calls to set and setqq 
appearing in type in are also converted to appropriate calls to saveset. | | 


For top level variables, saveset also adds the variable to the appropriate spelling list, thereby 
noticing variables set in files via град or градд, as well as those set via type in. 


Property list operations, (і.е., put, addprop and remprop) are handled specially so that they are always independent, 
even when they affect the same property list. For example, if the user types PUT(FOO FIE1 FUM1) then 
PUT(FOO FIE2 FUM2), then undoes the first event, the FIE2 property will remain, even though CDR(FOO) may 
have been NIL at the time the first event was executed. 

67 setq is made undoable by substituting savesetq, setqq by savesetqq, both of which are implemented in terms of 
saveset. | | 

68 Of course, UNDO can be used as long as the event containing this call to saveset is still active. Note however that the 
old value will remain on the property list, and therefore be recoverable via unset, even after the original event has 
been forgotten. 


69 


To complete the analogy with define, saveset will not save old values on property lists if dfnflg- T, e.g., when load 
is called with sccond argument Т, (however, the call to savcset will still be undoable), and when dfnflg = ALLPROP, 
the value is stored directly on the property list under property VALUE (the latter applies only to calls from града and | 


град). 
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UNDONLSETQ AND RESETUNDO 


The function undonlsetq provides a limited form of backtracking: if an error occurs under the 


. undonisetq, all undoable side effects executed under Ше undonlsetq are undone. resetundo, for use 
сіп conjunction with resetlst and resetsave (Section 5), provides a more general undo capability in 


that the user can specify that the side effects be undone after the specified computation finishes, is | 


aborted by an error, or by a control-D. undonlsetq and resetundo are described in detail on page 


22.43. 


22.7 FORMAT AND USE ОҒ THE HISTORY LIST 


There are currently two history lists, lispxhistory and edithistory. Both history lists have the same 
format, and in fact, each use the same function, historysave, for recording events, and the same set 
of functions Гог implementing commands that refer to the history list, е. £^ historyfind, prnthistory, | 
undosave, etc. SP | 


Each history list is a list of the form (1 event# size mod), where 1 is the list of events with the 
most recent event first, event# is the event number for the most recent event on 1, size is the size 
of the time-slice, i.e., the maximum length of 1, and mod is the highest possible event t number (see 
footnote on page 22. 7). lispxhistory and edithistory are both initialized to (NIL 0 30 100). Setting 
lispxhistory or edithistory to NIL is permitted, and simply disables all history features, i.e., 
lispxhistory and edithistory act like flags as well as repositories of events. 


Each individual event on 1 is a list of the form (input id value . props) where input is the input 


sequence for the event, as described on page 22.15-16, id the prompt character, . ер, ©, i, ",' and. 
value is the value of the event, and is initialized to bell.’ | | -— SNL 


props is a property list, i.e., of the form (property value property value --). props can be used to 
associate arbitrary information with a particular event. Currently, the properties SIDE, 
*ARCHIVE*, *GROUP*, *HISTORY*, *PRINT*, USE-ARGS, .ARGS,  *ERROR*, 
*CONTEXT* ‘and *| ISPXPRINT* аге being used. The value of property SIDE isa list of the side 
effects of the event. (See discussion of undosave, page 22.41, and undolispx, page 2242.) The 
*HISTORY* and *GROUP* properties are · used for commands that reexecute previous events, 1.е., 
REDO, RETRY, USE, ..., and FIX. The value of the *HISTORY* property is the history 


command itself, те. what the user actually typed, e.g., REDO FROM Е, and is used by Ше ?? 


command for printing the event. The value of the property *PRINT* is also for use by the 77 


command, when special formatting is required, for example, in printing events corresponding to Ше _ 
break commands OK, GO, EVAL, and ?=. USE-ARGS and ..ARGS are used to save the / 


arguments and expression for the corresponding history command. *ERROR* and *CONTEXT* are | 
used to save information when errors occur for subsequent use by Ше $ and ? commands. The - 
property *ARCHIVE* on an event causes the event to be automatically archived when it "falls off - 
the end" of the history list (see page 22.28). *LISPXPRINT* is used to record calls to lispxprint, 
lispxprinl, et al, (see page 22.30). a 


70 A third history list, archivelst, is used when events are archived, as described on page 22.23. It too uses the same 
A format. 

n id is one of the arguments to lispx and to historysave. А user can call lispx giving it any prompt character he wishes 
(except for ", since in certain cases, lispx must use the value of id to tell whether or not it was called from the 
editor.) For example, on page 22.29, the user's prompt character was **, 

72 


_ On edithistory, this field is used to save the side effects of each command. 
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When lispx is given an input, it calls historysave to record the input in a new event.? Normally, 
historysave returns as its value the new event. lispx binds lispxhist to the value of historysave, 50 


that when the operation has completed, lispx knows where to store the value, namely іп caddr of 


lispxhist./^ lispxhist also provides access to the property list for the current event. For example, 
the / functions are all implemented to call undosave, which simply adds the corresponding 
information to lispxhist under the property SIDE, or if there is no property SIDE, creates one, 

and then adds the information. | О 


After binding lispxhist, lispx executes the input, stores its value in caddr of lispxhist, prints the 
value, and returns. 


When Ше input is a REDO, RETRY, USE, .., or FIX command, the procedure is similar, except 
that the event is also given а *GROUP* property, initially NIL, and a *HISTORY* property, and 
lispx simply unreads the input and returns. When the input is "reread", it is historysave, not lispx, 
that notices this fact, and finds the event from which the input originally сате. > historysave then 
adds а new (input id value . props) entry to the *GROUP* property for this event, and returns this 
entry as the "new event." lispx then proceeds exactly as when its input was typed directly, i.e., it 
binds lispxhist to the value of historysave, executes the input, stores the value in caddr of lispxhist, 
prints the value, and returns. Іп fact, lispx never notices whether it is working on freshly typed 
input, or input that was reread. Similarly, undosave will store undo information on lispxhist under 
the property SIDE the same as always, and does not know or care that lispxhist is not the entire 
event, but one of the elements of the *GROUP* property. Thus when the event is finished, its 
entry will look like: 3 | | 
(input id value *HISTORY* command *GROUP* .  ((inputl idl valuel SIDE sidel) 

(input2 id2 value2 SIDE side2) | 


“) 


This implementation removes the Burden from the function calling. Огу Аё of distinguishing 
between new input and reexecution of input whose history entry has already been set up.’ 


22.8 LISPX AND READLINE 
lispx is called with the first expression typed on a line as its first argument, lispxx. 


If this is not a list, lispx always does a readline, and treats lispxx plus the line as the input for the 


73 The commands 7, FORGET, TYPE-AHEAD, $BUFS, and ARCHIVE аге executed immediately, and are not 
recorded on the history list. 


74 Мое that by the time it completes, the operation may no longer correspond to the most recent event on the history. 
list. For example, all inputs typed to a lower break will appear later on the history list. 

75 If historysave cannot find the event, for example if a user program unreads the input directly, and not via a history 
command, historysave proceeds as though the input were typed. 

76 In this case, the value field is not being used; valueof instead collects each of the values from the *GROUP* 
property, ie, returns mapcar[listget[cvent; * GROUP * ] ; CADDR]. Similarly, undo operates by collecting the SIDE 
properties from each of the elements of the *GROUP* property, and then undoing them in reverse order, 

77 


Although we have not yet done so, this implementation, i.c, keeping the various "sub-events" scparate with respect 
to values and propertics, also permits constructing commands for operating on just one of the sub-events. 
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event, and stores it accordingly on the history 1151.78 Then it decides what to do with the input, i.e., 


if it is not recognized as a command, a lispxmacro, or is processed by li lispxuserfn, call eval or 
apply. 79 readline normally is terminated either by (1) а сагпаде return that is not preceded А by a 
space, or (2) а list that is terminated by а | ог (3) an unmatched ) ог |, which is not included in 
the line. However, when called from lispx, readline operates differently in two respects: 


(1) Ifthe line consists of a single ) or |, readline returns (NIL) instead of NIL, i.e., the ) ог 
] is included in the line. This permits the user to type FOO) or FOO], meaning call the 
function’ FOO. with no arguments, as opposed to FOO. (FOOcarriage- return), meaning 
evaluate the variable FOO. | 


(2 If the first expression on the line is a list that 15 not preceded by any spaces, the list 
| terminates the line regardless of whether or not it is terminated бу |. This permits the 
user to type EDITF( FOO) as a single input. 


_ Note that if any spaces are inserted between the atom and Ше left parentheses or bracket, readline 


will assume that the list does not terminate the line. This is to enable the user to type a line 
command such as USE (FOO) FOR FOO. In this case, a carriage return will be typed after (FOO) 

followed by ".." as described in Section 14. Therefore, if the user accidentially puts an extra space 
between a function and its arguments, he will have to complete the input with another carriage | 
return, е.р., | 


«ЕРІТЕ (FOO) 
ыы 

ЕОТТ 
ст 


22.9 FUNCTIONS 


Пера (перхл, slispxid;lispxxmacros; lispxxuserfnf? | | 
`1їбрх is like eval/apply. It carries out а single computation, апа | 
returns its value. The first argument, lispxx is the result of a single | 
call to lispxread. lispx will call readline, if necessary as described · 


on page 22.35. lispx prints the value of the computation, as well as 


saving the input and value on lispxhistory.9! 


If lispxx is a history command: lispx calls historysave, executes the © 
command, and returns the value of historysave. 


В ү lispxx is а list car of which is LAMBDA ог NLAMBDA, lispx calls lispxread to obtain the arguments, 

7 ү the input consists of one expression, eval is called; if two, apply; if more than two, the entire line is treated as a 
single form and eval is called. | 

80 Jispxid corresponds to id on PAGEREF 1.47. Lispx also has a fifth argument, lispxflg, which is used by the E 
command in the editor. | 


Note that the history is лог one of the arguments to lispx, ie, the editor must bind (reset) lispxhistory to edithistory 
before calling lispx to carry out a history command. 

Lispx will continue to operate as an cval/apply function if lispxhistory is NIL. Only those functions and commands 
that involve the history list will be affected. 
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| If the value of the fourth argument, lispxxmacros, is not NIL, it is 
| used as the lispx macros, otherwise Ше top level value of 

| lispxmacros is used. If the value of the fifth argument, 
lispxxuserfn, is not NIL, it is used as lispxuserfn. In this case, it is 
not necessary to both set and define lispxuserfn as described on 
page 22.29. 


The overhead for a call to lispx (in Interlisp-10) is approximately 17 milliseconds, of which 12 
milliseconds are spent in maintaining the spelling lists. In other words, in Interlisp, the user pays 
17 more milliseconds for each eval or apply input over a conventional LISP executive, in order to 
enable the features described in this chapter. 


userexec[lispxid; lispxxmacros; lispxxuserfn] | 
repeatedly calls Берк. under errorset protection specifying 
lispxxmacros and lispxxuserfn, and using lispxid (or ¢ if 
lispxid=NIL) as a prompt character. Userexec is exited via the 
lispxmacro OK, or else with a retfrom. 


lispxread[file;rdtb]] is a generalized read. The value of readbuf is a list of expressions - 
read[file;rdtbl] which it returns as its value. (If the user types 


control-U during the call to read, lispxread calls the editor and | 
returns the edited value.) | 


If readbuf is not NI L, lispxread "reads" the next expression on 
readbuf, i.e., essentially returns p Жы 
(PROG1 (CAR READBUF) | 

(SETQ READBUF (CDR READBUF )) ).83 


readline, described in Section 14, also uses this generalized notion of reading. When readbuf is not 
NIL, readline "reads" expressions from readbuf until it either reaches the end of readbuf, or until 
it reads a pseudo-carriage return (see page 22.15). In both cases, it returns a list of the expressions 
it has "read". (The pseudo-carriage return is not included i in the list.) 


When readbuf is not NIL, both lispxread and readline actually obtain their input by performing 
(APPLY* LISPXREADFN FILE), where lispxreadfn is initially set to READ. Thus, if the user 
wants lispx, the editor, break, et al to do their reading via a different input function, e.g., uread, he 
simply sets lispxreadfn to the name of that function (or an appropriate LAMBDA expression), 


82 * 


Note: the user should only add expressions to readbuf by using the function lispxunread, since it knows about the 
format of readbuf. 


83 


Except that pseudo-carriage returns, as represented by the valuc of histstr0, are ignored, i.e., skipped. Lispxread also 
sets rereadflg to NIL when it reads via read, and sets rercadflg to the value of readbuf when rereading. 


22.37 


that have been ипгеад.82 If readbuf=NIL, lispxread performs * | | 


+ + + + + + + + + 


+ + 


Section 22: Тһе Programmer’s Assistant 


lispxreadp[flg] | isa T readp. If flg— T, lispxreadp returns T if there is 
| any input waiting to be "read", а la lispxread. If flg=NIL, 
lispxreadp returns T only if there is any input waiting to be "read" 
on this line. Іп both cases, leading spaces are ignored, i.e., skipped 
over with readc, so that if only spaces have been typed, lispxreadp 

will return NIL. 


lispxunread[Ist;-]  unreads Ist, a list of expressions to be read. 


promptchar[id;flg;history] prints the prompt character id. 


promptchar will not print anything when the next input will be | 
"reread", ie., readbuf is not NIL. promptchar will also not print 
when геадр = T, unless flg is T. E | | 


Thus the editor calls promptchar with flg- NIL so that extra “5 are not printed wien the user | 


types several commands on one line. However, суа] calls promptchar with йе = T, since it always 
wants the + printed (except when "rereading"). | 


Finally, if prompt йр is T and history is not NIL, promptchar 
prints the current event number (of history) before printing id. 


The value of promptcharforms is a list of expressions to be evaluated by promptchar before, and if, 
it does any printing. If promptchar is going to print something, it first maps down 
promptcharforms evaluating each expression under an errorset. These expressions can be 
conditioned on the values of history, id, and promptstr, which is what promptchar will print before 
id, if anything, e.g. when prompt Z Ае is T, promptstr will be the event number. The expressions 
on promptcharforms can be executed for effect, e.g. to change the shape of a cursor, update a 
clock, check for mail, etc. or to change what promptchar is about to print by resetting id and/or | 
promptstr.*4 After promptcharforms have been evaluated, promptstr is printed if it is (still) 

non-NIL, and then id is printed, if it is (still) non-NIL. | 


 lispxeval[lispxform;lispxid] evaluates lispxform (using eval) the same as though it were typed in 


to lispx, ie. the event is recorded, and the evaluation is made 
undoable by substituting the slash functions for the corresponding 
destructive functions, as described on page 22.32. lispxeval returns | 
the value of the form, but does not print it. POLI 


historysave[history ;id;inputl;input2;input3;props] | | | 
records one event on history. If inputl is not NIL, the input is of 
the form (inputl input2 . input3). If inputl is NIL, and input2 is - 
not NIL, the input is of the form (input2 . input3). Otherwise, the 
input is just input3. 


84 promptcharforms initially contains the expression (CHECKNIL) which checks to sce if саг ог cdr of NIL have been | 


clobbered, or NIL or T have becn reset or rebound, and if so, restores them and prints a warning message. 
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historysave creates a new event with the corresponding input, id, 
value field initialized to bell, and props. If the history has reached 
its full size, the last event is removed and cannibalized. | 


The value of historysave is the new event. However, if rereadflg is 
not NIL, and the most recent event on the history list contains the 
history command that produced this input, historysave does not 
create a new event, but simply adds an (input id bell . props) entry 
to the *GROUP* property for that event and returns that entry. 
See discussion on page 22.35. 


historysaveforms is a list of expressions that are evaluated under errorset protection each time 
historysave creates a new event, i.e. each time there was an interaction with the user, but not when 
performing an operation that is being redone. The expressions on historysaveforms are presumably 
executed for effect, and can use the value of history and id, as well as the value of event, which 1s 
the current, about to be executed, event, i.e. the value historysave is going to return. 


lispxstorevalue[event;value] ^ used by lispx for storing the value of an event. Can be advised by 
| user, e.g. to watch for particular values or perform other monitoring 
functions. | 


lispx find[history ;line;type;backup;-] | 
line is an event specification, type specifies the format of the value 
to be returned by lispxfind, and can be either ENTRY, ENTRIES, 
COPY, COPIES, INPUT, or REDO. lispxfind parses line, and 


uses historyfind to find the corresponding. events. lispxfind then. 


assembles and returns the appropriate structure. 
lispxfind incorporates the following special features: 


1) if backup- T, lispxfind interprets line іп the context of the history list before the current event 
was added. This feature is used, for example, by valueof, so that (VALUEOF -1) will not 
refer to the valueof event itself; 


2) ifline-NIL and the last event is an UNDO, the next to the last event is taken. This permits 
the user to type UNDO followed by REDO or USE; 


3) Нѕрхбпӣ recognizes @@, and substitutes archivelst for history (see page 22.12); and 


4)  lispxfind recognizes (2, and retrieves the corresponding event(s) from the property list of the 
atom following (0), 


history find[Ist;sindex;mod;eventadr;-] 
searches Ist and returns the tails of Ist beginning with the event 
corresponding to eventadr. Ist, index, and mod аге as described on 
page 22.34. cventadr is an суспі address, as described on page 
22.10-12, ср. (43), (-1), (FOO FIE), (LOAD e FOO), etc. If 
historyfind cannot find x, it generates an error. 
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entry # [hist;x] 


valueof[x] 


. changeslice[n;history;-] 
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соо рас; дын сас Бу historyfind for "matching" when eventadr specifies a 


pattern. Matches pat against input, the input portion of the history 
event event. Initially defined as editfindp[input;pat; T], but can be 
advised or redefined by the user. 


hist is a history list, i.c., of the form described on page 22.34. x is 
one of the events оп hist, ie. (MEMB X (CAR HIST)) is true. 
The value of entry Z is the event number for x. 


is an nlambda, nospread function for obtaining the value of the 
event specified by x, e.g., (VALUEOF -1), (VALUEOF LOAD 1), 
etc. valueof returns a list of the corresponding values if x specifies 
a multiple event. 


changes time-slice for history to n. If history is NIL, changes both 
edithistory and lispxhistory. 


Note: the effect of increasing a time-slice is gradual: the history list is simply allowed to grow to 
the corresponding length before any events are forgotten. Decreasing a time-slice will immediately 
remove a sufficient number of the older events to bring the history list down to the proper size. 
However, changeslice is undoable, so that these events are (temporarily) recoverable. Thus if the 
user wants to recover the storage associated with these events without waiting n more events for 
the changeslice event to be forgotten, he must perform a FORGET command. 


. saveset[name;value;topflg;flg] an undoable set (see page 22.33). saveset scans the pushdown list 


looking for the last binding of name, sets name to value, and | 
returns value. 


If the binding changed was a top level binding, name is added to 
spellings3 (see Section 17). Furthermore, if the old value was not 
NOBIND, and was also not equal to the new value, saveset calls the 
file package to update the necessary file records. Then, if dfnflg is 
not equal to T, saveset prints (name RESET), and saves the old 
valuc on the property list of name, under the property VALUE. If 
Пр = NOPRINT, saveset saves the old value, but does not print the 
message. This option is used by unset. 


If topflg = T, saveset operates as above except that it does not scan 
the pushdown list but goes right to name's value cell, e.g. 
rpaqq[x:y] is simply saveset[x;y;T]. When topflg is T, and dfnflg is 
ALLPROP and thc old value was not NOBIND, savcset simply stores 
value on the property list of name under the property VALUE, and 
returns value. This option is used for loading files without 
disturbing the current value of variables (see Section 14). 


If flg = NOSAVE, saveset docs по! save the old value on the property 
list, nor does it add name to spellings3. However, the call to 
savesct is still undoable. ‘This option is uscd by /set. If 
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unset[name] 


undosave[undoform;-]9? 


/rplnode[x;a;d] 
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flg - NOSTACKUNDO, saveset is undoable only if the binding being 


changed is a top-level binding, те. this says when resetting а 
variable that has been rebound, don't bother to make it undoable. 
This option is used by град, града, and addtovar. 


if name does not contain a property VALUE, unset generates an 
error. Otherwise unset calls saveset with name, the property value, 
topflg — T, and йр  NOPRINT. 


if lispxhist is not NIL (see discussion on page 22.35), and 
get[lispxhist;SIDE] is not equal to NOSAVE, undosave adds 
undoform to the value of the property SIDE on lispxhist, creating a 
SIDE property if one does not already exist. Тһе form of 


undoform is (fn. агрѕ),86 i.e., undoform is undone by performing | 
apply[car[undoform]; cdr[undoform]]. For example, if the definition. 


of FOO is def, /putd[FOO;newdef] will cause a call undosaye with 
undoform -(/PUTD. FOO def). 


car of the SIDE property is the number оғ" нда қ i.e., length 


of cdr of the SIDE property, which is the list of undoforms, Each 
call to undosave increments this count, and adds undoform to the 
front of the list, 1.е., just after the count. When the count reaches 
the value of #undosaves (initially 50),87 undosave prints a message 
asking the user if he wants to continue saving.” If the user answers 
NO or defaults, undosave discards the previously saved information 
for this event, and makes NOSAVE be the value of the property 


SIDE, which disables any further saving for this event. If the user — 
answers YES, undosave changes the count to -1, which is then never. 


incremented, and continues saving. 


Ра 


Undoably performs грѓасајк:ај and rplacd[x;d] Value is x. 


Generates an error, ILLEGAL ARG, if x is not a list. The principle 
advantage of /rplnode is that when x is a list, /rplnode saves its 
undo information as | cons[x;cons[car[x]:;cdir[x]]], ie., 
(x originalcar . originalcdr), and therefore requires only 3 cells of 
storage, instead of the 8 that would be required for a /rplaca and a 


Undosave has a second optional argument, histentry, which can be used to specify li spxhist If both histentry and | 


lispxhist are NIL, undosave is a no-op. 


If #undosaves is negative, when the count reaches | undosaves|, undosave simply stops saving without printing any 


86 Except for /rplnode, as described below. 
87 #undosaves=NIL is equivalent to # undosaves = infinity. 
88 
messages or interacting with the user. 
89 


load initializes the count on SIDE to -1, so that regardless of the value of # undosaves, no message will be putes 
and the load will be undoable. 
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_ /rplacd that saved their information as described earlier.” 


/rplnode has a BLKLIBRARYDEF. 


/ rplnode2[x;y] | same as / rplnode[x:carly]:cdrfy]. 


Note: for consistency, there are definitions for both rplnode and гріпойе2, although there primary 


reason for existence is the undoable versions. 


new/fn[fn] After the user has defined /fn, new/fn performs the necessary 
housekeeping operations to make fn be ша 


For example, the user could define / /radix as 
(LAMBDA (X) (UNDOSAVE (LIST (QUOTE /RADIX) (RADIX X)))and then perform 
new/fn[radix], and radix would then be undoable when typed in or in testmode. | 


lispx/[x;fn;vars] performs the substitution of / functions for destructive functions. 
If fn is not NIL, it is the name of a function, and x is its argument. 
list. If fn is NIL, x is a form. In both cases, lispx/ returns x with © 
the appropriate substitutions. Vars is a list of bound variables 
(optional). 


lispx/ incorporates information about the syntax and semantics of 
Interlisp expressions. For example, it does not bother to make 
undoable operations involving variables bound in x. It does not 
perform substitution inside of expressions car of which is NLAMBDA, 
i.e., has argtype 1 or 3 (unless car of the form has the property 
INFO value EVAL, as described in Section 20). For example, 
(BREAK PUTD) typed to lispx, will break on putd, not /putd. 
Similarly, substitution should be performed in the arguments for 
functions like тарс, rptq, etc., since these contain expressions that 
will be evaluated or applied. For example, if the user types 
тарс[ (F001 F002 F003);PUTD] the putd must be replaced by - 


/putd. 
undolispx[line] line is an event specification. undolispx is the function that 
executes UNDO commands by calling undolispx] on the appropriate 
entry(s). 
undolispxl[event;flg;-] undoes one event. The value of undolispxl is NIL if there is 


nothing to be undone. If the event is already undone, undolispxl 


90 Actually, /rplaca and /rplacd also use this format for saving their undo information when their first arguments аге - 
lists. However, if both a /rplaca and /rplacd are to be performed, it is still more efficient to use /rplnode (3 cells 
versus 6 cells). | 


22.42 


Functions 


prints ALREADY UNDONE and returns T.?! Otherwise, undolispx] 
| | undoes the event, prints a message, e.g, SETQ UNDONE, and 
| | returns Т. 


Undoing an event consists of mapping down (cdr of) the property value for SIDE, and for each 
element, applying car to cdr, and then marking the event undone by attaching (with /attach) a NIL 
to the front of its SIDE property. Note that the undoing of each element on the SIDE property 
will usually cause undosaves to be added to the current lispxhist, thereby enabling the effects of 
undolispxl to be undone. 


undonlsetq[form;-] is ап nlambda function similar to nlsetq. undonlsetq evaluates 
form, and if no error occurs during the evaluation, returns 
lisifeval[form]l and passes the undo information from form (if any) | 
upwards.?? If an error does occur, the value of undonlsetq is NIL, 
and any changes made by / functions during the evaluation of form 
are undone. 


undonlsetq compiles open. 


undonlsetq will operate even if lispxhistory Or lispxhist are NIL, or 
if #undosaves is or has been exceeded for this event, or is * 


exceeded while under the scope”? of the undonilsetg. ш 
resetundo[x;stopflg] For use in conjunction with resetlst (Section 5). resetundo[] 


initializes the saving of undo information and returns a value which 
when given back to resetundo undoes the intervening side effects. 


For example, (RESETLST (RESETSAVE (RESETUNDO)) . forms) will undo the side effects 
of forms on normal exit, or if an error occurs or a control-D is typed. Note that (UNDOLSETQ 
form) could be written as: 


1 ү Пр-Т and the event is already undone, or is an undo command, undolispxl takes no action and returns NIL. 
Undolispx uses this option to search for the last event to undo. Thus when line=NIL, undolispx simply searches 
history until it finds ап event for which  undolispxl returns T, іе,  undolipx performs 
(SOME (CDAR LISPXHISTORY) (F/L (UNDOLISPX1 X T))) | 

92 Actually, undonlsetq does not rebind lispxhist, so that any undo information is stored directly on the history event, 

exactly as though there were no undonlsetq. Instead, undonisetq simply marks the state of the undo information 

when it starts, so that if an error occurs, it can then know how much to undo. The purpose of this is so that if the 
user control-D's out of the undonlsetq, the event is still undoable, 


93 


Caution must be exercised in using coroutines or other non-standard means of exiting while under an undonlsetg. * 


Sce discussion under CHANGING AND RESTORING SYSTEM STATE in Section $5, 
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(RESETLST (RESETSAVE. (RESETUNDO) 


. forms) 


For example, 


(AND (EQ RESETSTATE ' ERROR) 
| (RESETUNDO OLDVALUE) )) 


If stopflg = T, resetundo cx accumulating undo information it is 
saving on x. 


(RESETLST (SETQ FOO (RESETUNDO)) 
(RESETSAVE NIL (LIST 'RESETUNDO ЕОО)) 
(ADVISE --) | 
(RESETUNDO FOO Т) 


. forms) 


would cause the advice to be undone, but not any of the side effects in forms. 


printhistory[history;line;skipfn;novalues; file] 


line is an event specification. printhistory prints the events on 


history specified by line, e.g. (-1 THRU -10). Printing is 
performed via the function showprin2, so that if the value of 
sysprettyflg — T, events will be prettyprinted. skipfn is an (optional) 
functional argument that is applied to each event before printing. | 
If its value is true, the event is skipped, ie. not printed. If 


. novalues- T, or novalues applied to the corresponding event is true, 


the value is not printed.” 


For example, the following lispxmacro will define ?" as a command for printing the ыу list 
while skipping all "large events" and not printing any values. 


(??' (PRINTHISTORY LISPXHISTORY LISPXLINE 


(FUNCTION (LAMBDA (X) 
(IGREATERP (COUNT (CAR X)) 5))) 


. T T)) 


Note that this has no bearing on the saving of undo information on higher resetundo's, or on being able to undo the 


entire event, 


For example, novalues is T when printing events on cdithistory. 
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22.10 THE EDITOR AND THE РКОСКАММЕК 5 ASSISTANT 


As mentioned earlier, all of the remarks concerning "the assistant" apply equally well to user 


interactions with evalqt, break ог the editor. The differences between the editor's implementation 
of these features and that of lispx are mostly obvious or inconsequential. However, for 
completeness, this section discusses the editor's implementation of the programmer's assistant. 


The editor uses promptchar to print its prompt character, and lispxread, lispxreadp, and readline 
for obtaining inputs. When the editor is given an input, it calls historysave to record the input in a 
new event on its history list, edithistory.’ Edithistory follows the same conventions and format as 
lispxhistory. However, since edit commands have no value, the editor uses the value field for 
saving side effects, rather than storing them under the property SIDE. | 


The editor recognizes and processes the four commands DO, ТЕ, !F, and IN commands which 
refer to previous events on edithistory. The editor also processes UNDO itself, as described below. 
All other history commands"' are simply given to lispx for execution, after first binding (resetting) 
lispxhistory to edithistory. The editor also calls lispx when given an E command as described in 
Section 9. 


The major implementation difference between the editor and lispx occurs in undoing. Edithistory 
is a list of only the last n commands, where n is the value of the time-slice. However the editor 
provides for undoing ай changes made in a single editing session, even if that session consisted of - 
more than n edit commands. Therefore, the editor saves undo information independently of the 
edithistory on a list call undolst, (although it also stores each entry on undolst in the field of the 
corresponding event on edithistory.) Thus, the commands UNDO, 10100, and UNBLOCK, are not 
dependent on edithistory,’’ i.e., UNDO specifies undoing the last command on undolst, even if that 
event no longer appears on edithistory. The only interaction between UNDO and the history list 
occurs when the user types UNDO followed by an event specification. In this case, the editor calls 
lispxfind to find the event, and then undoes the corresponding entry on undolst. Thus the user 
can only undo a specified command within the scope of the edithistory. (Note that this is also the 
only way UNDO commands themselves can be undone, that is, by using the history feature, to 
specify the corresponding event, e.g., UNDO UNDO.) 


The implementation of the actual undoing is similar to the way it is done in lispx: each command 
that makes a change in the structure being edited does so via a function that records the change on 
a variable. After the command has completed, this variable contains a list of all the pointers that 


96 Except that the atomic commands OK, STOP, SAVE, P, ?, PP and E are not recorded. In addition, number 


commands are grouped together in a single event. For example, 3 3 -1 is considered as one command for changing 
position. 
37 as indicated by their appearance on historycoms, a list of the history commands. editdefault interrogates historycoms 
before attempting spelling correction. (АП of the commands on historycoms are also on editcomsa and editcomsl so 
that they can be corrected if misspelled in the editor.) Thus if the user defines a lispxmacro and wishes it to operate 
in the editor as well, he nced simply add it to historycoms. For example, RETRIEVE is implemented as a lispxmacro 
and works equally well in lispx and the editor. | 
98 та this case, the editor uses the fifth argument to lispx, lispxflg, to specify that any history commands аге to be 
executed by a recursive call to lispx, rather than by unreading. For example, if the user types Е REDO in the editor, 
he wants the last event on lispxhistory processed as lispx input, and not to be unread and processed by the editor. 


99 


and in fact will work if cdithistory=NIL, or even in a system which docs not contain lispx at all. 
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have been changed and their original contents. Undoing that command simply involves mapping 
down that list and restoring the pointers. | | (| 


22.11 STATISTICS 


Тһе programmer's assistant keeps various statistics about system usage, e.g., number of lispx inputs, 


number of undo saves, number of calls to editor, number of edit commands, number of p.a. 
commands, cpu time, console time, et al. These can be viewed via the function lispxstats. 


lispxstats[returnvaluesflg] prints statistics. If returnvaluesflg — T, returns the statistics as a list 
| of elements of the form (value . explanation). | 


The user can add his own statistics to the lispx statistics via the function addstats. | 


_addstats[statlst] no spread, nlambda. Statlst is a list of elements of the form 


(statistic-name . message), eg. (EDITCALLS CALLS ТО 
EDITOR) (UNDOSTATS CHANGES UNDONE), etc. statistic-name 
is set to the cell in an unboxed array, where the corresponding 
statistic will be stored. "This statistic can then be incremented by 


lispxwatch. 
lispxwatch[stat;n] increments stat bs n (or 1 if п= МИ). lispxwatch has а 
BLKLIBRARYDEF. 


The user can save his statistics for loading into а new system Әу performing 
MAKEFILE(DUMPSTATS). After the Ме DUMPSTATS is loaded, the statistics printed by lispxstats - 
will be the same as those that would be printed following the makefile. 


22.12 GREETING AND USER PROFILES. 


Many of the features of Interlisp are parameterized to allow the user to adjust the system to his ог 


. her own tastes. Among Ше more commonly adjusted parameters аге prompt Пр, dwimwait, 


changeslice, #rpars, lowercase, archivefn, #undosaves, fltfmt, etc. In addition, the user сап 
modify the action of system system functions in ways not ыы гуша for by using advise 
(Section 19). 


In order to encourage this procedure, and to make it as painicis and automatic as possible, the 5s | 
includes a facility for both a site-profile and a user-defined profile. When Interlisp is first run, it 
looks for a file on the LISP directory, with name INIT, extension LISP, and if one is found, loads 
the file. This provides a way of setting defaults for a particular community of users, patching bugs, | 
etc. Interlisp then looks on the user's login directory for a file with name INIT, extension LISP, 
and if one is found, loads that. In both cases, the loads are performed "silently" by rebinding 
prettyheader (Section 14) to NIL. The p.a. then prints a greeting, e.g, "HELLO, WARREN." or 
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"GOOD AFTERNOON, DANNY.", с.100 


. Greeting (i.e, the initialization) is undoable, and is stored as a separate event on the history list - 


The user can also specifically invoke the greeting operation via the function greet, for example, if 
he wishes to effect another user’s initialization. 


greet[name] performs greeting for user whose username is name, or if 


name = NIL, for login name (see username and usernumber, Section 
21) ie. when Interlisp first starts up, it performs greet[]. Before 
greet performs the indicated initialization, it first undoes the effects 
of the previous greeting. , | 


greet also sets the variable username to the name for which the greeting was performed, 


100 


101 


102 


The p.a. uses the value of firstname in greeting the user. firstname should be set in the user’s INIT.LISP file. In 
addition, the value of greetdates can be used to specify special greeting messages for various dates. greetdates is a 
list of elements of the form (datestring . string), e.g. ("25-DEC" . "Merry Christmas"). The user can add entries to 
this list in his/her INIT.LISP file, ер. by using a prettydef command like (ADDVARS (GREETDATES ("21- 
FEB" . "Happy Birthday"))). On the specified date, Ше p.a. will use the indicated salutation. If the user 
wishes his functions to be time stamped (see Section 9) with his initials when edited, he should also include a 
prettydef command (ADDVARS (INITIALSLST (username . initials))). 


The side effects of the greeting operation are stored on a global variable as well as the history list, thus enabling the 
previous greeting to be undone even if it is no longer on the history list. 


In addition, makesys is advised to undo the effects of the previous greeting, thereby returning the system to a pristine 
state. — | 
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SECTION 23 
CLISP - CONVERSATIONAL LISP! 


23.1 INTRODUCTION 


The syntax of LISP is very simple, in the sense that it can be described concisely, but not in the 
sense that LISP programs are easy to read or write! This simplicity of syntax is achieved by, and 
at the expense of, extensive use of explicit structuring, namely grouping through parenthesization. 
Unlike many languages, there are no reserved words in LISP such as IF, THEN, AND, OR, FOR, 
DO, BEGIN, END, etc., nor reserved characters like +, -, *, /, =, *, etc.? This eliminates entirely 
the need for parsers and precedence rules in the LISP interpreter and compiler, and thereby makes 
program manipulation of LISP programs straightforward. In other words, a program that "looks 
at" other LISP programs does not need to incorporate a lot of syntactic information. For example, 
a LISP interpreter can be written in one or two pages of LISP code ({McCl], pp. 70-71). It is for 
this reason that LISP is by far the most suitable, and frequently used, programming language for  . 
writing programs that deal with other programs as data, e.g., programs that analyze, modify, or | 

construct other programs. 


However, it is precisely this same simplicity of syntax that makes LISP programs difficult to read 
and write (especially for beginners) "Pushing down’ is something programs do very well, and 
people do poorly. As an example, consider the following two "equivalent" sentences: 


"Тһе rat that the cat that the dog that I owned chased caught ate the cheese." 
versus 
"I own the dog that chased the cat that caught the rat that ate the cheese." 


Natural language contains many linguistic devices such as that illustrated in the second sentence 
above for minimizing embedding, because embedded sentences are more difficult to grasp and 
understand than equivalent non-embedded ones (even if the latter sentences are somewhat longer). 
Similarly, most high level programming languages offer syntactic devices for reducing apparent 
depth and complexity of a program: the reserved words and infix operators used in ALGOL-like 
languages simultancously delimit operands and operations, and also convey meaning to the 
programmer. They are far more intuitive than parentheses. In fact, since LISP uses parentheses 
(1.е., lists) for almost all syntactic forms, there is very little information contained in the parentheses 


CLISP was designed and implemented by W. Teitelman. It is discussed in [Teis]. 


except for parentheses (and period), which are used for indicating structure, and space and end-of-line, which are 
used for delimiting identifiers. 
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for the person reading a LISP program, and so the parentheses tend tnostly to be ignored: the 
meaning of a particular LISP expression for people is found almost entirely in the words, not in the 
structure. For example, the following expression 

(COND (EQ N 0) 1) (T TIMES N FACTORIAL ((SUB1 N))) 
is recognizable as FACTORIAL even though there are five misplaced or missing parentheses. 
Grouping words together in parentheses is done more for LISP’s benefit, than for the 
programmer's. | 


CLISP is designed to make Interlisp programs easier to read and write by permitting the user to 


employ various infix operators, IF-THEN-ELSE statements, 
FOR-DO-WHILE-UNLESS- FROM-TO- -etc. expressions, which are automatically converted to 
equivalent Interlisp expressions when they are first interpreted. - For example, FACTORIAL could 
be written in CLISP: 

(IF М=0 THEN 1 ELSE N*(FACTORIAL N-1)) 


Note that this expression would become an equivalent COND after it had been interpreted once, so 
that programs that might have to analyze or otherwise process this expression could take advantage 


= of ihe simple syntax. 


There have been similar efforts in other LISP systems, most notably the MLISP language а 
Stanford [Smil]. CLISP differs from these in that it does not attempt to replace the LISP syntax 
50 much as to augment it. In fact, one of the principal criteria in the design of CLISP was that 
users be able to freely intermix LISP and CLISP without having to identify which is which. Users 
can write programs, or type in expressions for evaluation, in LISP, CLISP, or a mixture of both. 


_ In this way, users do not have to learn a whole new language and syntax in order to be able to use 


selected facilities of CLISP when and where they find them useful. 


 CLISP is КЕНЕНІ via the error correction machinery іп Interlisp (see Section 17). Thus, any 


expression that is well-formed from Interlisp’s standpoint will never be seen by CLISP (i.e., if the 
user defined a function IF, he would effectively turn off that part of CLISP). This means that 
interpreted programs that do not use CLISP constructs do not pay for its availability by slower 
execution time. In fact, the Interlisp interpreter does not "know" about CLISP at all. It operates 
as before, and when an erroneous form is encountered, the interpreter calls an error routine which 
in turn invokes the Do-What-I-Mean (DWIM) analyzer which contains CLISP. If the expression 


in question turns out to be a CLISP construct, the equivalent Interlisp form is returned to the 


interpreter. In addition, the original CLISP expression, is modified so that it becomes the correctly 
translated Interlisp form. In this way, the analysis and translation are done only once. 


Integrating CLISP into the Interlisp system (instead of, for example, implementing it as a separate 
preprocessor) makes possible Do-What-I-Mean features for CLISP constructs as well as for pure 
LISP expressions. For example, if the user has defined a function named GET-PARENT, CLISP 
would know not to attempt to interpret the form (СЕТ-РАКЕКТ) as an arithmetic infix operation. 


(Actually, CLISP would never get to sce this form, since it does not contain any errors) If the 


user mistakenly writes ( GET-PRAENT), CLISP would know he meant (GET-PARENT), and not 
(DIFFERENCE GET PRAENT), by using the information that PRAENT is not the name of a 
variable, and that GET-PARENT is the name of a user function whose spelling is "very close" to 
that of GET-PRAENT. Similarly, by using information about the program's environment not 
readily available to a preprocessor, CLISP can successfully resolve the following sorts of 
ambiguities: | 


1) (LIST Х*ЕАСТ М), where FACT is the name of a variable, means (LIST (X*FACT) М). 
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2) (LIST X*FACT N), where FACT is not the name of a variable but instead is the r name | а 
function, means (LIST X*(FACT N)), ie, М 15 FACT's argument. 


3) (LIST X*FACT(N)), FACT the name of a function (and not the name of a variable), 
means (LIST X*(FACT N)). 


4) cases (1), (2) and (3) with FACT misspelled! 


The first expression is correct both from the standpoint of CLISP syntax and semantics and the 
change would be made without the user being notified. In the other cases, the user would be 
informed or consulted about what was taking place. For example, to take an extreme case, suppose 
the expression (LIST X*FCCT N) were encountered, where there was both a function named 
FACT and a variable named FCT. The user would first be asked if FCCT were a misspelling of 
FCT. If he said YES, the expression would be interpreted as (LIST (X*FCT) N).? If he said 
NO, the user would be asked if FCCT were а misspelling of FACT, i.e., if he intended X*FCCT М 

to mean X*(FACT N). If he said YES to this question, the indicated transformation would be 
performed. If he said NO, the system would then ask if X*FCCT should be treated as CLISP, 

since FCCT is not the name of a (bound) variable^ If he said YES, the expression would be 
transformed, if NO, it would be left alone, i.e., as (LIST X*FCCT М). Note that we have not 
even considered the case where X*FCCT is itself a misspelling of a variable name, e.g., a variable 
named XFCT (as with GET-PRAENT). This sort of transformation would be considered after the 
user said NO to X*FCCT М -? X*(FACT М). The graph of the possible interpretations for 
(LIST X*FCCT N) where FCT and XFCT are the names of variables, and FACT is the name die 
function, is shown in Figure 23-1 below. 


Through this discussion, we speak of CLISP or DWIM asking the user. Actually, if the expression in question was - 
typed in by the user for immediate execution, the user is simply informed of the transformation, on the grounds that 
the user would prefer an occasional misinterpretation rather than being continuously bothered, especially since he can 
always retype what he intended if a mistake occurs, and ask the programmer’s assistant to UNDO the effects of the 
mistaken operations if necessary. For transformations on expressions in user programs, the user can inform CLISP 
whether he wishes to operate in CAUTIOUS or TRUSTING mode. In the former case (most typical) the user will be 
asked to approve transformations, in the latter, CLISP will operate as it does on type-in, ie, perform the 
transformation after informing the user, 


This question is important because many Interlisp users already have programs that employ identifiers containing 
CLISP operators. Thus, if CLISP encounters the expression А/В in a context where either A or В are not the names 
of variables, it will ask the user if А/В is intended to be CLISP, in case the user really does have a free variable 
named A/B. 
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The final states for the various terminal nodes shown in the graph are: 


1: (LIST (TIMES X FCT) М) 

2: (LIST (TIMES X (FACT N))) 
3: (LIST XFCT М) 

4: (LIST (TIMES X FCCT) М) 
5: (LIST X*FCCT М) 


CLISP can also handle parentheses errors caused by typing 8 or 9 for "(" or ")". (On most 
terminals, 8 and 9 are the lower case characters for "(" and ")", i.e., "(" and "8" appear on the 
same key, as do ")" and "9") For example, if the user writes N*8FACTORIAL N-1, the 
parentheses error can be detected and fixed before the infix operator * is converted to the Interlisp 
function TIMES. CLISP is able to distinguish this situation from cases like N*8*X meaning 
(TIMES N 8 X), or N*8X, where 8X is the name of a variable, again by using information about 
the programming environment. In fact, by integrating CLISP with DWIM, CLISP has been made 
sufficiently tolerant of errors that almost everything can be misspelled! For example, CLISP can 
successfully translate the definition of FACTORIAL: 


(IFF №0 THENN1 ESLE N*8FACTTORIALNN-1) 
to the corresponding COND, while making 5 spelling corrections and fixing the parenthesis error.° 


This sort of robustness prevails throughout CLISP. For example, the iterative statement permits 
the user to say things like: 


FOR OLD X FROM М TO N DO (PRINT X) WHILE (PRIMEP X) 


However, the user can also write OLD (Хем), (OLD Хем), (OLD (X«M)), permute the order 
of the operators, e.g; DO PRINT X TO М FOR OLD ХеМ WHILE PRIMEP X, omit either or 
both sets of parentheses, misspell any or all of the operators FOR, OLD, FROM, TO, DO, or 
WHILE, or leave, out the word DO entirely! And, of course, he can also misspell PRINT, | 
PR IMEP, M or М? 


CLISP is well integrated into the Interlisp system. For example, the above iterative statement 
translates into an equivalent Interlisp form using PROG, COND, GO, etc? When the interpreter 


5 CLISP also contains а facility for converting from Interlisp back to CLISP, so that after running the above incorrect 
definition of FACTORIAL, the user could "CLISPIFY" the now correct LISP version to obtain 
(ТЕ М=0 THEN 1 ELSE N*( FACTORIAL М-1)). 

6 This expression should be self explanatory, except possibly for the operator OLD, which says X is to be the variable 
of iteration, i.e., the one to be stepped from N to M, but X is not to be rebound. Thus when this loop finishes _ 
execution, X will be equal to N* 1. 

7 


In this example, the only thing the user could not misspell is the first X, since it specifies the name of the variable of 
iteration. The other two instances of X could be misspelled. 


8 (PROG NIL 

(SETQ X M) 

$$LP(COND | 

((OR (IGREATERP X N) (NOT (PRIMEP X))) 
(RETURN) ) ) | 

(PRINT X) 
(SETQ X (ADD1 X)) 
(GO $$LP)) 
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subsequently encounters this CLISP expression, it automatically obtains and evaluates the 
translation? Similarly, the compiler "knows" to compile the translated form. However, if the user 


. PRETTYPRINTSs his program, at the corresponding point in his function, PRETTYPRINT "knows" 


to print the original CLISP. Similarly, when the user edits his program, the editor keeps the 
translation invisible to the user. If the user modifies the CLISP, the translation is automatically 
discarded and recomputed the next time the expression is evaluated. 


In short, CLISP is not a language at all, but rather a system. It plays a role analagous to that of 
the programmer’s assistant (Section 22). Whereas the programmer’s assistant is an invisible 
intermediary agent between the user's console requests and the Interlisp executive, CLISP sits 
between the user's programs and the Interlisp interpreter. 


Only a small effort has been devoted to defining the core syntax of CLISP. Instead, most of the 
effort has been concentrated on providing a facility which "makes sense" out of the input 
expressions using context information as well as built-in and acquired information about user and 


System programs. It has been said that communication is based on the intention of the speaker to 


produce an effect in the recipient. CLISP operates under the assumption that what the user said 
was intended to represent a meaningful operation, and therefore tries very hard to make sense out 
of it. The motivation behind CLISP is not to provide the user with many different ways of saying 
the same thing, but to enable him to worry less about the syntactic aspects of his communication 
with the system. In other words, it gives the user a new degree of freedom by permitting him to 
concentrate more on the problem at hand, rather than on translation into a formal and 
unambiguous language. 


23.2 CLISP SYNTAX 


Throughout CLISP, а non-atomic form, i.e. а list, can always be substituted for a variable, and 
vice versa, without changing the interpretation. For example, if the value of (FOO X) is A, and 


the value of (ЕТЕ Y) is B, then (LIST (FOO X)+(FIE Y)) has the same value as 
(LIST A+B). Note that the first expression consists of a list of four elements: the atom "LIST", 


the list "(FOO X)", the atom "+", and the list "(FIE X)", whereas the second expression, 
(LIST A+B), consists of a list of only two elements: the atom "LIST" and the atom "A+B", 


Since (LIST (FOO X)+(FIE Y)) is indistinguishable from (LIST (FOO X) + (ЕТЕ Y)) 


because spaces before or after parentheses have no effect on the Interlisp READ рговгат,10 to be 
consistent, extra spaces have no effect on atomic operands either. In other words, CLISP will treat 
(LIST A+_B), (LIST A_+B), and (LIST A_+_B) the same as (LIST A+B). 


23.3 INFIX OPERATORS 


CLISP recognizes the arithmetic infix operators +, -, *, /, and t. These are converted to IPLUS, 


| See page 23.22, for discussion of how translations are stored. 


10 CLISP does not use its own special READ program because this would require the user to explicitly identify CLISP 


_ expressions, instead of being able to intermix Interlisp and CLISP. 
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IDIFFERENCE (or in the case of unary minus, IMINUS), ITIMES, IQUOTIENT, and EXPT.ll 
The usual precedence rules apply (although these can be easily changed by the user),!? i.e., * has 
higher precedence than + so that A+B*C is the same as A+(B*C), and both * and / are lower 
than 7 so that 2#Хт2 is the same as 2%(Х72). Operators of the same precedence group from left 
to right, e.g., A/B/C is equivalent to (А/ B)/C. Minus is binary whenever possible, i.e., except 
when it is the first operator іп a list, as in (-А) or (-A), or when it immediately follows another 
operator, as in A*-B, 3 14 


Note that grouping with parentheses can always be used to override the normal precedence 
grouping, or when the user is not sure how a particular expression will parse. 


CLISP also recognizes as infix operators =, GT, LT, GE, and (Е,І5 as well as various 
predicates, e.g, MEMBER, AND, OR, EQUAL, "ес16 AND is higher than OR, e.g., 
(X OR Y AND Z) isthe sameas (X OR (Y AND Z)), and both AND and OR are lower than the 
other infix operators, e.g., (X AND Y EQUAL Z) is the same as (X AND (Y EQUAL Z)). АП о 
the infix predicates have lower precedence than Interlisp forms, i.e., (FOO X GT FIE Y) is the 
same as ((Ғ00 X) GT (FIE Y)), since it is far more common to apply a predicate to two 
forms, than to use a Boolean as an argument to a function, e.g., (FOO (X GT (FIE Y))). 
However, again, the user can easily change this. 


Note that only single character operators, eg, +, ©, =, etc, can appear in the interior of an 
atom. All other operators must be set off from identifie iers with spaces. For example, XLTY will not 
be recognized as СІІЅР,!! | 


11 Тһе I іп IPLUS denotes integer arithmetic, ie., IPLUS converts its arguments to integers, and returns an integer 


value. Interlisp also contains floating point arithmetic functions as well as mixed arithmetic functions (see Section 13). 
Floating point arithmetic functions are used in the translation if one or both of the operands are themselves floating 
point numbers, e.g., X+1.5 translates as (FPLUS X 1.5). In addition, CLISP contains a facility for declaring 
which type of arithmetic is to be used, either by making a global declaration, or by Separate declarations about 
individual functions or variables. See section on declarations, page 23.24. 


12 The complete order of precedence for CLISP operators is given in Figure 23-2, page 23.9. 


13 There are some do-what-I-mean features associated with Unary minus, as in (LIST -X Y). See section on 
operation, page 23.51. 

14 Note that + in front of a number will disappear when the number is read, e.g., (FOO X +2) is indistinguishable 
from (FOO X 2). This means that (FOO X +2) will not be interpreted as CLISP, or be converted to 
(FOO (IPLUS X 2)). Similarly, (FOO X -2) will not be interpreted the same as (FOO X-2). To circumvent 
this, always type a space between the + or - and a number if an infix operator is intended, e.g. write 
(FOO X + 2). 


15 Greater Than, Less Than, Greater than or Equal to, and Less than or Equal to, respectively. GT, LT, GE, and LE 
are all affected by the same declarations as -- and *, with the initial default to use IGREATERP and ILESSP. 


16 Currently the complete list is MEMBER, MEMB, FMEMB, ILESSP, IGREATERP, LESSP, GREATERP, FGTP, 
EQ, NEQ, EQP, EQUAL, OR, and AND. New infix operators can be easily added, as described in the section on 
CLISP internal conventions, page 23.53. Spelling correction on misspelled infix operators is peformed using | 


clispinfixsplst as a spelling list. 


17 [n some cases, DWIM will be able to diagnose this situation as a run-on spelling error, in which case after the atom 


is split apart, CLISP will be able to perform the indicated transformation. 
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: is an infix operator used іп CLISP for extracting substructures from 1155,28 e.g., X:3 specifies the 
3rd element of X, (FOO Y)::2 specifies the second tail of (FOO Y), i.e, (CDDR (FOO Y)), 
and Z:1:2 is the second element of the first element of Z, or (CADAR Z). Negative numbers 
may be used to indicate Em counting from the end of a list, E X:-1 is the last element of 
X, or (CAR (LAST X)), : -1 is the last fail, i.e., (LAST X). 


е is used to indicate assignment, e.g., XeY translates to (SETQ X Ү).20 21 In conjunction with : 
and ::, * can also be used to perform a more general type of assignment, namely one involving 
Structure modification. For example, X:2¢Y means make the second element of X be Y, in 
Interlisp terms (RPLACA (CDR X) Y). 22 23 Negative numbers can also be used, e.g., X:-2¢Y. м e 

is also used to indicate assignment іп record operations, page 23.25, and pattern match operations 
(Section 24). 


с has different precedence on the left from on the right. On the left, € is a "tight" operator, i.e., 
high precedence, so that АчВеС is the same as A+(BeC). On the right, « has broader scope 50 
that AeB+C 15 the same as Ac (B+C ). 


On typein, $«form ( < esc > <form) is equivalent to set the "last thing mentioned".2? For example, 


immediately after examining the value of LONGVARIABLENAME, the user could set it by typing di 
followed за а form. 


23.4 PREFIX OPERATORS 


CLISP recognizes " and ~ as prefix operators. ” means QUOTE when it is the first character in ап 
identifier, and is ignored when it is used in the interior of an identifier. Thus, X='Y means — 
(EQ X (QUOTE Y)), but X=CAN'T means (EQ X CAN'T), not (EQ X CAN) followed by 


The record facility, page 23.25, provides another way of extracting substructures by allowing the user to assign 

names to the various parts of the structure and then retrieve from or store into the corresponding structure by name. 

The pattern match facility (Section 24) also can be used to extract substructure. : is also used to indicate both record 

and pattern match operations. 

19 The interpretation of negative numbers can be explained neatly in terms of edit commands: :-n returns what would . 

be the current expression after executing the command -n, and ::-n returns what would be the current expression 

after executing -n followed by UP. | 

0. If x does not have а value, and is not the name of one of the bound variables of the function in which it appears, 
spelling correction is attempted. However, since this may simply be a case of assigning an initial value to a new ' free 
variable, DWIM will always ask for approval before making the correction. | 

21 Note that an atom of the form X«Y, appearing at the top level of a PROG, will not be recognized as an assignment 

statement because it will be interpreted as a PROG label by the Interlisp interpreter, and therefore will not cause an | 

error, so DWIM and CLISP will never get to see it. Instead, one must write (X€Y). 


22 Note that the value of this operation is the value of rplaca, which is the corresponding node. 


The user can indicate he wants /rplaca and /rplacd used (undoable version of rplaca and rplacd, see Section 22), or 
frplaca and frplacd (fast versions of rplaca and rplacd, see Section 5), by means of declarations (page 23.24). The 
initial default is for rplaca and rplacd. 


24 which translates to (RPLACA (NLEFT X 2) У). 


25 i.e., is equivalent to (SETQ lastword form). See Section 17. 
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(QUOTE T). This enables users to have variable and function names with ' in them (so long as- 


the ' is not the first character). 


Following ’, all operators are ignored for the rest of the identifier, e.g., ' "А means ЛЕ *A), 
and "Х-Ү means (QUOTE X=Y), not (EQ (QUOTE X) Y). 26 | 


On typein, $ (е. ° < esc») is equivalent to (QUOTE value- E (5% Section 17). For. 


example, after calling prettyprint on LONGFUNCTION, the user could move its definition to FOO by 
typing (MOVD '$ 'FOO). | | 


^ means NOT. - can negate a lom as іп ~(ASSOC X Y), ог ~X, ог negate an infix operator, 
e.g., (a ~GT B) is the same as (A LEQ В). Note that ~A=B means E б А) В). 


Order of Precedence of CLISP me 


є (left precedence) 28 
- (unary), ~ ш 
4 

ж / 

+, - (binary) 


* (right precedence) 


Interlisp forms 
LT, GT, ЖМ MEMBER, etc. 
AND 


IF, THEN, ELSEIF, ELSE 
iterative statement operators 


Figure 23-2 


6 то write (EQ (QUOTE Х) Y), one writes Y='X, or 'X «Ү. This is one place where an extra space does make a 
difference. 


27 Not (МОМО $ "ЕОО), which would be equivalent to (МОМО LONGFUNCTION "ЕОО), and would (probably) 


cause a U.B.A. LONGFUNCTION error, nor MOVD($ FOO), which would actually move the definition of $ to FOO, 
since DWIM and the spelling corrector would never be invoked. 


B , has a different left and right. precedence, e.g., A+B«C+D is the same as. несвесно). In other words, e has 
minimal scope on the left and maximal scope on the right. 


29 When ~ negates an operator, e.g., ~ =, ~LT, the two operators are treated as a single operator whose precedence is 
that of the second operator. When ~ negates a function, e.g, (~FOO X Y), it negates the whole form, i.e., 
(~(FOO X Y)). 
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23.5 CONSTRUCTING LISTS - THE < AND > OPERATORS? 


Angle brackets are used in CLISP to indicate list construction. The appearance of a "<" 
corresponds to a "С and indicates that a list is to be constructed containing all the elements цр to 
the corresponding ’>’. For example, <A B <C>> translates to (LIST АВ (LIST С)). ! can 
be used to indicate. that the next expression is to be inserted in the list as a segment, e.g., 
<A B ! С> translates to (CONS A (CONS B C)) ала <! A 1 B C> to 
(APPEND A B (LIST C)). !! is used to indicate that the next expression is to be inserted as a 
segment, and furthermore, all list structure to its right in the angle brackets is to be physically 
attached to it, eg, <!! А B> translates и (NCONC1 A B), ала <!!А ІВ ІС> to. 
(NCONC А (APPEND B C)).?! 32 Note that <, 1, И, and > need not be separate atoms, for _ 
example, <A B ! C> may be written equally well as € A B ІС >. Also, arbitrary Interlisp or . 
"СР forms may be used within angle brackets. For example, one can write 
<FOO+(FIE X) | Y> which translates to (CONS (SETQ FOO (ЕТЕ X)) Y). CLISPIFY 
converts expressions in cons, list, append, nconc, nconcl, /nconc, and /nconcl into equivalent 
CLISP expressions using <, >, l and П. | 


Моје: brackets differ from other CLISP operators. For example, <А B "Со translates to 
(LIST. i B (QUOTE C)) even though following ', all operators are ignored for the rest of the 
identifier Note however that <А B ' C> D> is equivalent to (LIST A B (QUOTE C>) D). 
Section 23.17 describes how the user can define his own bracketing operators, 


23. 6 IF, THEN, ELSE 


CLISP translates expressions employing IF | THEN | ELSEIF | ELSE. into equivalent conditional 
expressions. The segment between IF ЈЕ ЗЕТЕ and the next THEN corresponds to the predicate of 
а COND clause, and the segment between THEN and the next ELSE|ELSEIF as the consequent(s). 
ELSE is the same as ELSEIF T THEN. | 


ТЕ, THEN, ELSE, and ELSEIF are of lower precedence than all infix and prefix Operators, as 
well as Interlisp forms, so that parentheses can be omitted between IF|ELSEIF, and ТНЕМ.34 For 
example, (IF FOO X Y THEN --) is equivalent to (IF (FOO X Y) THEN --).35 Similarly, 
CLISP treats (IF X THEN FOO X Y ELSE --) as equivalent to 
(IF X THEN (FOO X Y) ELSE --) because it does not "make sense" to evaluate a variable 
for effect. In other words, even if FOO were also the name of a variable, (COND (X FOO X Y)) 
doesn't make sense. Essentially, CLISP determines whether the segment between THEN and the 


The <,> operator was written by P.C. Jackson. 


| 31 Not (NCONC (APPEND A В) С), which would have the same vane: but would attach C to В, and not attach 
either to A. 


The user can indicate /nconc or /nconcl be used instead of nconc and nconcl by declarations. 


3 Only if a previous unmatched < has been seen, e.g., (PRINT 'А?В) will print the atom ADB. 


34 IF, THEN, ELSE, and ELSEIF сап also be misspelled. өре correction is performed using clispifwordsplst as a. 


spelling list. 
35 If FOO is the name of a variable, IF Ғ00 THEN -- is translated as (COND (FOO --)) even if FOO is also the 


name of a function. If the functional interpretation is intended, FOO should be ене іп parentheses, e.g., 
ІР (FOO) THEN -- . Similary for IF -- THEN FOO ELSEIF --. 
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next ELSE|ELSEIF corresponds to one form or several and acts accordingly.36 Thus, 
(IF -- THEN (FOO X) Y ELSE --) corresponds to a clause with two consequents. Similarly, 
(IF -- THEN 2006Х Y ELSE --) corresponds о. а clause with two  Consequents, and is 
equivalent to (IF -- THEN (ЕООеХ) Y ELSE --).37 


23.7 ITERATIVE STATEMENTS 
The following is an example of a CLISP iterative statement: 
(WHILE Xe(READ)-s'STOP DO (PRINT (EVAL X))) 


This statement says "READ an expression and set X to it. If X is not equal to the atom STOP, then 
evaluate X, print the result, and iterate." 


The 1.5. (iterative statement) in its various forms permits the user to specify complicated iterative 
statements in a straightforward and visible manner. Rather than the user having to perform the 
mental transformations to an equivalent Interlisp form using PROG, МАРС, MAPCAR, etc., the 


system docs it for him. The goal was to provide a robust and tolerant facility which could "make © 


sense" out of a wide class of iterative statements. Accordingly, the user should not feel obliged to 
read and understand in detail the description of each operator given below in order to use iterative 
statements. | 


Currently, the following is. operators are implemented: FOR, BIND, OLD, IN, ON, FROM, 


TO, BY, WHEN, WHILE, UNTIL, REPEATWHILE, REPEATUNTIL, UNLESS, COLLECT, 
JOIN, DO, SUM, COUNT, ALWAYS, NEVER, THEREIS, AS, FIRST, FINALLY, 


EACHTIME. Their function is explained below. New operators can be defined as described on 


page 23.19. Misspellings of o operators are recognized and corrected.?? The order of appearance of 
operators is never important? CLISP scans the entire statement before it begins to construct the 
equivalent Interlisp form. | | 


ЕЕ 


occasionally interacting with the user to resolve ambiguous cases. 
37 To write the equivalent of a singleton cond clause, i.e., a clause with a predicate but no consequent, write either | 
nothing following the THEN, or omit the THEN entirely, eg, (IF (FOO X) THEN ELSEIF --) or 
(IF (FOO X) ELSEIF --), meaning if (FOO X) is not NIL, it is the value of the сопа, | 
38 The statement translates to: 
(PROG ($$VAL) 
$$LP(COND 
((EQ (SETQ X (READ)) (QUOTE STOP)) | 
(RETURN $$VAL))) 
(PRINT (EVAL X)) 
$$1TERATE (GO $$LP)) 
39 using the spelling list clispforwordsplst. 


40 рум and CLISP are invoked on iterative statements because car of the is. is not the name of a function, and 
. hence generates an error. If the user defines a function by the same name as ап i.s. operator, e.g., WHILE, TO, etc., 
the operator will no longer have the CLISP interpretation when it appears as car of a form, although it will continue 
to be treated as an i.s. operator if it appears in the interior of an i.s. To alert the user, a warning message is printed, 


c.g., (WHILE DEFINED, THEREFORE DISABLED IN CLISP). 
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00 form 


COLLECT form | 


JOIN form 


SUM form | 


COUNT form 


ALWAYS form 


NEVER form 


. THEREIS form 
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specifies what is to be done at each iteration. DO with no other operator 
specifies an infinite loop. If some explicit or implicit terminating 
condition is specified, the value of the is. is NIL. Translate to MAPC or 
MAP whenever possible. 


like DO, except specifies that the value of form at each iteration is to be 
collected in a list, which is returned as the value of the i.s. when it 
terminates. Translates to MAPCAR, MAPLIST or SUBSET whenever 
possible.^ 


like DO, except that the values are NCONCed. Translates to MAPCONC or 
MAPC он whenever роввіМе,42 


. like DO, except specifies that the values of form at each iteration be added 


together and returned as Ше value of the is, ешр, 
(FOR I FROM 1 TO 5 SUM 172) is equal to 1+4+9-+16+2543 


like DO, except counts number of times that form is true, and returns that 
count as its value. 


like DO, except returns T if the value of form is non-NIL for all iterations | 
(returns NIL as soon as the value of form is NIL), eg, | 
(FOR X IN Y ALWAYS (ATOM X)) is the same аз 

(EVERY Y (FUNCTION АТОМ)). | 


like ALWAYS, except returns T if the value of form is never true, i.e., 
NEVER form is the same as ALWAYS ~form. 


| returns the first value of the iv. for which form is non-NIL, e.g., 


(FOR Х ІМ Ү ТНЕВЕТ5 NUMBERP) returns the . first number in Y, and 
is equivalent to (CAR (SOME Y (FUNCTION NUMBERP)) ).4 


when COLLECT translates to a PROG, e.g, a WHILE operator appears in the iterative statement, the translation 


employs an open tconc using two pointers similar to that used by the compiler for compiling mapcar. To disable this. 
translation, perform cldisable[F COLLECT]. 


42 /NCONC, /MAPCONC, and /MAPCON аге used when the declaration UNDOABLE is in effect. 


43 


iplus, fplus, or plus will be used for the translation depending on the declarations in effect. 


THEREIS returns the iv. instead of the tail (as does the function some) in order to provide an interpretation 


consistent with statements such as (FOR І FROM 1 TO 10 THEREIS --), where there is no tail. Note that 
(SOME Y (FUNCTION NUMBERP)) is equivalent to 
(FOR X ON Y THEREIS (NUMBERP (CAR X))). 
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DO, COLLECT, JOIN, SUM, ALWAYS, NEVER, and THEREIS are examples of а certain kind 
of is. operator called an is.type. The i.s.type specifies what is to be done at each iteration. Its 
operand is. called the body of the iterative statement. Each is. must have one and only one 
i.s.type. 


FOR var specifies the variable of iteration, or i.v., which is used in conjunction with 
| ІМ, ОМ, FROM, TO, and BY. Тһе variable is rebound for the scope of 
the i.s., except when modified by OLD as described below. 


FOR vars vars a list of variables, e.g, FOR (X Y Z) IN --. The first variable is 
the i.v., the rest are dummy variables. See BIND below. 


OLD var indicates var is not Юю be rebound, e.g., 
(FOR OLD X FROM 1 TO М DO -- UNTIL --), 


BIND var, vars used to specify dummy variables, e.g. FOR (X Y Z) IN -- is 
equivalent to FOR X BIND (Y Z) IN --. BIND can be used without 
FOR. For example, in the 15. shown on page 23.11, X could be made 
local by writing (BIND X WHILE Хе(ВЕАО)-+ "5ТОР...). 


Note: FOR, OLD, and BIND variables can be initialized by using е, eg. 
(FOR OLD (Xeform) BIND (Yeform)...). | 


IN form specifies that the 1.5. is to iterate down а list with the i.v. being reset to 
the corresponding element а each iteration. For example, 


FOR X IN Y DO -- corresponds | to 


(MAPC Y (FUNCTION (LAMBDA (X) --))). If no iv. has been 
specified, a dummy is supplied, e.g., IN Y COLLECT CADR is equivalent 
to (MAPCAR Y (FUNCTION CADR)). 


ON form | same as IN except that the i.v. is reset to the corresponding tail at each 
iteration. Thus IN corresponds to МАРС, MAPCAR, and МАРСОМС, 
while ON corresponds to MAP, MAPLIST, and MAPCON. BEEN 


Note: for both IN and ON, form is evaluated before the main part of the i.s. is entered, i.e. outside 
of the scope of any of the bound variables of the is. For example, 
(FOR X BIND Ye(LIST 1 2 3) IN Y --) will not map down (1 2 3). | 


ІМ OLD var specifies that Ше i.s. is to iterate down var, with var itself being reset to 
the corresponding tail at X each iteration, ер, after 
(FOR X IN OLD L DO -- UNTIL --) finishes, | will be some tail of 
its original value. 


IN OLD (vare form) same as IN OLD var, except var is first set to value of form. 
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ОМ 010 уаг 


ON OLD (уаг« form) 


INSIDE form 


WHEN form 


. UNLESS form 


WHILE form 
UNTIL form 


UNTIL n. 


REPEATWHILE form 


REPEATUNTIL form 


REPEATUNTIL n 


FROM form 


TO form 


iteration, e.g., INSIDE 


Same as WHILE except for difference in sign, 
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same as IN OLD var except the i.v. is reset to the current value of var at 
each iteration, instead of to car[var]. ! 


same as ON OLD var, except var is first set to value of form. 


like IN, except treats first non-list, non-NIL tail as the last element of the 
АВ C D . E) iterates five times with the i.v. 
set to E on the last iteration. Similarly, INSIDE 'A is equivalent to 
INSIDE " (А), i.e., will iterate once. 


For example, 
collects only the 


provides a way of excepting certain iterations. 
(FOR X ІМ Ү COLLECT X WHEN МОМВЕВР Х) 
elements of Y that are numbers. 


same as WHEN except for the difference in sign, i.e, WHEN 7 is the same 
as UNLESS ~2. 


. provides a way of terminating Ше is. WHILE form evaluates form before 
. each iteration, and if the value is NIL, exits. | 


ie, WHILE form is 
equivalent to UNTIL -Тогт. 


n a number, equivalent to UNTIL (ім. GT n). 


same as WHILE except the test is performed after the evalution of the 
body, but before the i Lv. is reset for the next iteration. 


same as UNTIL, except the test is performed after the evaluation of the 
body. 


n à number, equivalent to REPEATUNTIL (i.v., GT n). 


is used to specify an initial value for a numerical iv. The iv. is 
automatically incremented by 1 after each iteration 
(unless BY is specified). If no ім. has been specified, a dummy i.v. is 
supplied and initialized, e.g., (COLLECT SQRT FROM 2 TO 5) returns 
(1.414 1.732 2.0 2.236). 


If FROM is not 
If no iv. has been spccified, а 


is used to specify the final value for a numerical i.v. 
specified, the i.v. is initialized to 1. 
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dummy i.v. is supplied and initialized. If BY is not specified, the iv. is 
automatically incremented by 1 after cach iteration. When the iv. is 
definitely being incremented, i.e., either BY is not specified, or its operand 
is a positive number, the i.s. terminates when the i.v. exceeds the value of 


(FOR X FROM 1 UNTIL (X GT 10) --). 


Similarly, when the i.v. is definitely being decremented the is. terminates 
when the i.v. becomes Jess than the value of form (see description of BY). 


If IN or ON have been specified, the value s of form determines the fail for 
the next iteration, which in turn determines the value for the iv. as 
described earlier, i.e., the new i.v. is car of the tail for IN, the tail itself for 
ON. In conjunction with IN, the user can refer to the current tail within 
form by using the iv. or the operand for IN/ON, eg. 


(FOR Z IN L BY (CDDR Z) ...) ог | 


(FOR 2 IN L ВУ (CDDR |) ...). At translation time, the name of 
the internal variable which holds the value of the current tail is substituted 
for the i.v. throughout form. For ехатріе, 
(FOR X IN Y BY (CDR (MEMB 'FOO (CDR X))) COLLECT X) 
specifies that after each iteration, cdr of the current tail is to be searched 
for the atom ЕОО, and (саг of) this latter tail to be used for the next 
iteration. 


BY form РА IN/ON) 
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If IN ог ON have not been used, BY specifies how the i.v. itself is reset at 
each iteration. If FROM or TO have been specified, the i.v. is known to be 
numerical, so the new i.v. is computed by. adding the value of form 


(which is reevaluated each iteration) to the current value of the i.v., e.g., 


(FOR N FROM 1 TO 10 BY 2 COLLECT N) makes a list of the first 
five odd numbers. 


If form is a positive number,*’ the is. terminates when the value of the 
іу. exceeds the value of Т0% operand. If form is a negative number, the 
is. terminates when the value of the i.v. becomes less than ТО" operand, 
ер. (FOR I FROM М TO M BY -2 UNTIL (I LT M) ...). 
Otherwise, the terminating condition for each iteration depends on the 
value of form for that iteration: if form < 0, the test is whether the i.v. is 
less than TO's operand, if form > 0 the test is whether the i.v. exceeds 
TO's operand, otherwise if form = 0, Ше i.s. terminates unconditionally. _ 


except when both Ше operands to TO and FROM are numbers, and TO's operand is less than FROM's operand, e.g., 


FROM 10 TO 1, in which case the i.v. is decremented by 1 after each iteration. In this case, the 1.5. terminates 
when the i.v. becomes /ess than the value of form. | 
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form is evaluated only once, when the i.s. is first entered, and its value bound to a temporary variable against which 


the i.v. is checked each interation. If the user wishes to specify ап 1.5. in which the value of the boundary condition 
is recomputed each iteration, he should use WHILE or UNTIL instead of TO. 
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form itself, not its value, which in general CLISP would have no way of knowing in advance. 
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formé ер, (FOR X FROM 1 TO 10 --), is equivalent to — 


* 


FIRST form 
FINALLY form 


EACHTIME form 


AS var 


OUTOF form 


DECLARE: decl 


+ 
+ 
+ 
+ 
+ 
+ 
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If FROM or TO have not been specified and form is not a number, the i.v. 
is simply reset to the value of form after each iteration, ер, 
(FOR I FROM N BY M ...). (ds equivalent |. to 
(FOR I+N BY (IPLUS I M) ...). | 


form is evaluated once before the first iteration, e.g., 


(FOR X Y Z IN L -- FIRST (ЕОО Y Z)), and ЕОО could БЕ шей 


to initialize Y and Z. 


form is evaluated after the 1.5. terminates. For example, 
(FOR X IN L BIND Y«0 DO (IF АТОМ X THEN YeY41) 


FINALLY (RETURN Y)) will return the number of atoms іп |. 


form is evaluated at the beginning of each iteration before, and regardless 

of, any testing. For example, consider (FOR I FROM 1 TO N DO (... 

(FOO I) ...) UNLESS (... (FOO I) ...) UNTIL (... (FOO 
I) ...)). The user might want to set a temporary variable to the value 
of (FOO I) in order to avoid computing it three times each iteration. 
However, without knowing the translation, he would not know whether to 
put the assignment іп the operand to DO, UNLESS, or UNTIL, ie. 

which one would be executed first. He can avoid this problem by simply 
writing EACHTIME Је(ЕОО I). 


is used to specify an iterative statement involving more than one iterative 
variable, eg. (FOR X IN Y AS U IN V DO --) corresponds to 
map2c. The i.s. terminates when any of the terminating conditions are 
met, e.g, (FOR X IN Y AS I FROM I TO 10 COLLECT X) makes a 
list of the first ten elements of Y, or however many elements there are on 
Y if less than 10. 


The operand to AS, var, specifies the new i.v. For the remainder of the 
is. or until another AS is encountered, all operators refer to the new i.v. 
For example, (FOR I FROM I TO М1 AS J FROM 1 TO М2 BY 2 
AS K FROM N3 TO 1 BY -1 --) terminates when I exceeds N1, 
ог J exceeds М2, ог К becomes less than 1. After each iteration, I is 
incremented by 1, J by 2, and K by -1. | | 


for use with generators (Section 12). On each iteration, the i.v. is set to 
successive values returned by the generator. The i.s. terminates when the- 
generator runs out. 


inserts decl immediately following the prog variable list in the translation, 
or, in the case that the translation is a mapping function rather than a 
prog, immediately following the argument list of the lambda expression in 
the translation. For example 
(FOR X IN Y (DECLARE: (LOCALVARS X)) -- ). Several 


DECLARE :'s can арррсаг in the same 1.5.; the declarations аге inserted in 


the order they appear. 
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DECLARE decl same as DECLARE : 48 


ORIGINAL is.opr operand 


is.opr will be translated using its original, built-in interpretation, - 
independent of any user defined is. operators. See section on "Defining | 


New Iterative Statement Operators" below. 


MISCELLANEOUS 


19 


48 


49 


50 
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го) 


Each 1.5. operator is of lower precedence than all Interlisp forms, so parentheses around the 


operands can be omitted, and will be supplied where necessary, e.g., BIND (X У Z) can be 
written BIND X У Z, OLD (Xeform) as OLD Xeform, WHEN (NUMBERP X) as 
WHEN NUMBERP X, etc. | 


RETURN or GO may be used in any operand. (In this case, the translation of the iterative 
statement will always be in the form of a PROG, never a mapping function.) RETURN means 
return from the i.s. (with the indicated value), not from the function in which the i.s appears. 
GO refers to a label elsewhere in the function in which Ше 15. appears, except for the labels 
$$LP,$$ITERATE, and $$0UT which are reserved, as described in 6 below. 


In the case of FIRST, FINALLY, EACHTIME, DECLARE: or one of the i.soprs, e.g., DO, 
COLLECT, SUM, etc, the operand can consist of more than one form, ер, 
COLLECT (PRINT X:1) X:2, in which case a PROGN is supplied. 


Each operand can be the name of a function, in which case it is applied to the (last) 
İ.V., е.р., РОК X ІМ Ү DO PRINT WHEN МЏМВЕВР, 15 Ше same а 
FOR Х IN Y DO (PRINT X) WHEN (NUMBERP X). Note that the iv. need not be 
explicitly specified, e.g., ІМ Y DO PRINT WHEN NUMBERP will work. 


While the exact form of the translation of an iterative statement depends on which operators 
are present, a PROG will always be used whenever Ше i.s. specifies dummy variables, i.e., if a 
BIND operator appears, or there is more than one variable specified by a FOR operator, or a 
GO, RETURN, or a reference to the variable $$VAL appears in any of the корегш. When а 
PROG is used, the form of the translation is: 


Note that since declare is also the name of a function, DECLARE cannot be used as an i.s. operator when it appears 


as car of a form, i.e. as the first i.s. operator in an iterative statement. However, declare (lower-case version) can _ 


be the first 1.5. operator. 

For is.oprs, eg, DO, COLLECT, JOIN, the function is always applied to Ше first iv. in the is, whether explicity 
named or not. For example, (IN Y AS I FROM 1 TO 10 DO PRINT) prints elements on Y, not integers 
between 1 and 10. 


Note that this feature docs not make much sense for FOR, OLD, BIND, IN, or ON, since they “operate” before 
the loop starts, when the i.v. may not even be bound. 


In the case of BY in conjunction with IN, the function is applied to the current fail ед, 
FOR X IN Y BY CDDR ..., 15 Ше same as FOR X IN Y BY (CDDR X)... See page 23.15. 
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Lowercase versions of all is. operators are equivalent to the uppercase, e.g., (for X in Y. 
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(PROG variables 
. {initialize} 
$$LP {eachtime} 
{test} 
{body} 
$$ITERATE 
{aftertest} 
{update} 
(GO $$LP) 
$$OUT {finalize} 
(RETURN $$VAL)) 


where {test} corresponds to that portion of the loop that tests for termination and also for 
those iterations for which {body} is not going to be executed, (as indicated by a WHEN or 
UNLESS); {body} corresponds to the operand of the is.opr, e.g. DO, COLLECT, etc.; 
f{aftertest} corresponds to those tests for termination specified by REPEATWHILE ог 
REPEATUNTIL; and {update} corresponds to that part that resets the tail, increments the 
counter, etc. in preparation for the next iteration. {initialize}, {finalize}, and ieachtime] 
correspond to the operands of FIRST, FINALLY, and EACHTIME, if шу. 


Note that since {body} always appears at the top level of the PROG, the user can insert labels 
in {body}, and go to them from within {body} or, from other is. operands, eg, - 
(FOR X IN Y FIRST (60 А) DO (FOO) A (FIE)).?? The user can also go to $$LP, | 
$$ITERATE or $$0UT, or explicitly set $$VAL. 


то 


ERRORS IN ITERATIVE STATEMENTS | 


An error will be generated and an appropriate diagnostic printed if any of the folowing conditions | 


^* hold: 


1. 


2; 


2. 
6. 


Operator with null operand, i.e., two adjacent operators, as іп FOR X IN Y UNTIL DO -- 


Operand consisting of more than one form (except as operand to FIRST, FINAL LY, or one 


. of the i.s.oprs), e.g., FOR X IN Y (PRINT X) COLLECT --. 


IN, ON, FROM, TO, or BY appear twice in same i.s. 
Both IN and ON used on same i.v. 
FROM or TO used with IN or ON on same i.v. 


More than one i.s.type, e.g., a DO and a SUM. 


In 3, 4, or 5, an error is not generated if an intervening AS occurs. 


If an error occurs, the i.s. is left unchanged. 
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However, since {body} is dwimified as а list of. forms, the label(s) should be added to the dummy variables for the 
iterative statement in order to prevent their being dwimified and possibly "corrected", e.g., 
(FOR X IN Y BIND A FIRST (GO А) DO (FOO) A (ЕТЕ)). 
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If no DO, COLLECT, JOIN or any of the other is.oprs are specified, CLISP will first attempt to 
find an operand consisting of more than one form, e.g., 
.FOR X IN Y (PRINT X) WHEN ATOM X, and in this case will insert a DO after the first form. 
(In this case, condition 2 is not considered to be met, and an error is not generated.) If CLISP 
cannot find such an operand, and no WHILE or UNTIL appears іп the 15. a warning message is 
printed: NO DO, COLLECT, OR JOIN: followed by the is. 


Similarly, if no terminating condition is detected, іе. no IN, ON, WHILE, UNTIL, TO, or a 
RETURN or GO, a warning | message is | printed’: 

POSSIBLE NON-TERMINATING ITERATIVE STATEMENT: followed by the 1.5. However, since 
the user may be planning to terminate the 1.5. via an error, control-E, or a retfrom from a lower | 
function, the 1.5. is still translated. 


DEFINING NEW ITERATIVE STATEMENT OPERATORS 


The following function is available for defining new or redefining existing iterative statement - 
operators: | 


i.s.opr[name;form;others;evalflg] 
name is the name of the new 1.5. Орт. If form is а list, name will be 
a new is.type, and form its body.’ | 


For example, for COLLECT, form would be (SETQ $$VAL (NCONC1 $$VAL BODY) ) 
For SUM, form would be ($$VALe$$VAL-BODY ) ,55 others would be (FIRST S$VALe0). 
For NEVER: (IF BODY THEN $$VAL«NIL (GO $$0UT))), and for 

THEREIS: (IF BODY THEN $$VAL-I.V. (GO $$0UT)). 


others is an (optional) list of additional i.s. operators and operands 
which will be added to Ше i.s. at the place where name appears. If | 
form is NIL, name is a new i.s.opr defined entirely by others. 


In both form and others, $$VAL can be used to reference the value 
to be returned by the is. I.V. to reference the current i.v., and 
BODY to reference name's operand. 


53 — unless the value of clispi.s.gag is T. clispi.s.gag is initially NIL. 


The is.type is the is.opr that specifies what is to be done at each iteration, e.g., performing an operation (00); 
collecting values on a list (COLLECT), adding numbers (SUM), searching for a particular condition (THEREIS), 
etc. Each 1.5. can have one and only one 1.5. type. | 


55 $$VAL+BODY is used instead of ( IPLUS $$VAL BODY) so that the choice of function used in the translation, i.e., 
iplus, fplus, or plus, will be determined by the declarations then in effect. 

56 (ТЕ BODY THEN RETURN NIL) would exit from Ше is. immediately and therefore not execute Ше operations 

specified via a FINALLY (if any). 

7ш other words, the current i.v. will be substituted for all instances of I. V. and name's operand will be substituted 

for all instances of BODY throughout form and others. 
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If evalflg is T, form and others are evaluated at translation time, 
and their values ‘used as described above. 


If name was previously an is.opr and is being redefined, the 
message (name REDEFINED) will be printed (unless dfnflg — T), 
and all expressions using the 15.орг name that паш been translated 
will have their translations discarded. 


Examples: 


(1) To define RCOLLECT, a version of COLLECT which uses cons instead. of nconcl and then 
reverses the list of values: | 
LSopr[RCOLLECT; ($$VALe(CONS BODY $$VAL)); | 

(FINALLY (RETURN (DREVERSE $$VAL)))] 


(2) To define TCOLLECT, a version of COLLECT which uses (сопс: · 


is.opr[TCOLLECT;(TCONC $$VAL BODY); 
(FIRST SSVALe(CONS) | FINALLY (RETURN (CAR $5VAL)))] 


(3) To define ОЕ —— I IM $$VAL*1)] 


(4) To define UPTO, a version of TO whose operand is evaluated only once: 


i.s.opr[UPTO; NIL; (BIND $$FOO+BODY TO 55Ғ00) 1. 


(5) To redefine TO so that instead of recomputing form form each iteration, a variable is bound to the 
value of form, and then that variable is used: 
is.opr[ TO ; №1 NIL;(BIND ЗЗЕМО FIRST $$bEND-BODY ORIGINAL TO SSEND) | 

Note the use of ORIGINAL to redefine TO in terms of its original definition.’ 


1.5.орг сап also be used to define synonyms for already defined is. operators by calling is.opr with 
form an atom, e.g, is.op[WHERE; WHEN] makes WHERE be the same as WHEN. Similarly, 
following is.opr[ ISTHERE; THEREIS], one can write ( ISTHERE АТОМ IN Y), and following 
i.s.opr[ FIND; FOR] and i.s.opr[ SUCHTHAT ; THEREIS], one can write 
(FIND X IN Y SUCHTHAT X MEMBER 7).90 


58 Istvars is а list of dummy variable names used бу Ше iterative statement translator. If the user wishes to obtain a 
dummy variable for use in translation, and be sure it does not clash with a dummy variable already used by some 
other i.s. operators, he can use car of Istvars, and reset Istvars to cdr[Istvars]. 

59 ORIGINAL is intended for usc in redefining built-in operators, since their definitions аге not accessible, and hence 
not directly modifiable. Thus if Ше operator had been defined by the user via i.s.opr, ORIGINAL would not obtain · 
its original definition. In this case, one presumably would simply modify the i.s.opr definition. | 
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In the current system, WHERE 15 synonymous with WHEN, SUCHTHAT and ISTHERE with THEREIS, and FIND with 
FOR. 
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If form is the atom MODIFIER, then name is defined as an i.s.opr which can immediately follow 
another is. operator (ie. an error will not be generated, as described previously). name will not 
terminate the scope of the previous opcrator, and will be stripped off when dwimify is called on its 
operand. OLD is an example of а MODIFIER type of operator. The MODIFIER feature allows the 
user to define is. operators similar to OLD, for use in conjunction with some RENI user defined 
is.opr which will produce the appropriate translation 


For convenience, there is a file package command, I.S.OPRS, which dumps 15. орг, е.р., 


(I.S.OPRS PRODUCT UPTO) as a file package command will print suitable рио so that | 


these iterative statement operators will be (re)defined when the file is loaded. 


This completes the description of iterative statements. 


23.8 ENGLISH PHRASES 


CLISP also recognizes a limited but expandable set of english-like constructions of the form "A is 
B", eg, FOO IS A NUMBER, 2 IS МОТ A STRING, (СООК X) ISN'T А TAIL OF У. 
Both subject and relation can be "distributed", e.g., X AND Y ARE ATOMIC is equivalent to X IS 
ATOMIC AND Y IS ATOMIC. Similarly, Z IS AN ARRAY OR A LIST is equivalent to Z IS 
AN ARRAY OR 7 IS A LIST, and A AND B ARE NUMBERS AND LESS THAN 5 AND GT 0 
is equivalent to the conjunction of the indicated six predicates. These constructions are translated 


to the corresponding LISP expressions when they are run or ed In addition, clispity will | 


convert LISP forms into "english" when clispifyenglshflg is T. 


Clisp currently knows about the following unary relations in their singular and plural forms: 
ARRAY, ATOM, ATOMIC, FLOATING POINT NUMBER, LIST, LITATOM, LITERAL ATOM, 
NEGATIVE, NIL (ie, X IS NIL) NULL, NUMBER, SMALL INTEGER, SMALL NUMBER, 
STRING; and the following binary relations in their singular and plural forms: EQ TO, EQUAL 
TO, GEQ, GREATER THAN, GT, LESS THAN, LT, MEMB OF, MEMBER OF, TAIL OF. 

All relationships can be negated with either NOT, N, or N'T, eg, X IS -LESS THEN Y, À 
AND B AREN'T ATOMIC. New relations can be defined via the function newisword. 


newisword[sing;plu;form;vars] sing is the singular form of the new english construct, plu the plural 
without the subject. form is the form the singular construct 
translates to, and vars the parameters. 


For example, "SMALL INTEGER" could be defined by newisword[(X IS A SMALL INTEGER); 


(ARE SMALL INTEGERS); (SMALLP X); (01 and "TAIL OF" by newisword[(X IS A 
TAIL OF Y); (ARE TAILS OF Y); (TAILP X Y); (X Y)]. 
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23.9 CLISP TRANSLATIONS 


The translation of infix operators and IF|THEN|ELSE statements are handled in CLISP by 
replacing the CLISP expression with the corresponding Interlisp expression, and discarding the 
original CLISP, because (1) the CLISP expression is easily recomputable (by clispify), 61 and (2) the 


Interlisp expressions are simple and straightforward. In addition to saving the space required to 


retain both the CLISP and the Interlisp, another reason for discarding the original CLISP is that it 
may contain errors that were corrected in the course of translation, e.g., the user writes 
FOO+FO00:1, N*8FOO X), ек. If the original CLISP were retained, either the user would have 
to go back and fix these errors by hand, thereby negating the advantage of having DWIM perform 
these corrections, or else DWIM would have to keep correcting these errors over and over. 


Where (1) or (2) are not the case, e.g, with iterative statements, pattern matches, record 
expressions, etc.?^ the original CLISP is retained (or a slightly modified version thereof), and the 
translation is stored elsewhere, usually in clisparray, a hash array.9? 64 The interpreter automatically 
checks this array using gethash when given a form car of which is not a function.® Similarly, the 

compiler performs a gethash when given a form it does not recognize to see if it has a translation, _ 
which is then compiled instead of the form. Whenever the user changes a CLISP expresson by 
editing it, the editor automatically deletes its translation (if one exists), so that the next time it is 
evaluated or dwimified, the expression will be retranslated.99 The function ppt and the edit 
commands PPT and CLISP: are available for examining translations, see page 23.60. Similarly, if 
prettytranflg is T, prettyprint will print the translations instead of the corresponding CLISP | 
expression | 


61 Note that clispify is sufficiently fast that it is practical for the user to configure his Interlisp system so that all 
expressions are automatically clispifyed immediately before they are presented to him. For example, he can define an 
edit macro to use in place of P which calls clispify on the current expression before printing it. Similarly, he can 
inform prettyprint to call clispify on each expression before printing it, etc. 


62 The handling of ао Гог ТЕ | THEN|ELSE statements is determined by the value of clispiftranflg. If T, the 
translations are stored elsewhere, and the (modified) CLISP retained as described below. If NIL, the шаа 
COND replaces the IF | THEN|ELSE expression. The initial value of clispiftranflg is NIL. 


63 The actual storing of the translation is performed by the function clisptran, page 23.57. 


“Тһе user can also indicate that he wants the original clisp retained by embedding it in an expression of the form 
(CLISP . clisp-expression), eg, (CLISP X:5:3) or (CLISP <A B C | D>). In such cases, the 
translation will be stored remotely as described in the text. Furthermore, such expressions will be treated as clisp 

. even if infix and prefix transformations have been disabled by setting clispflg to NIL, as described on page 23.56. In 
other words, the user can instruct the system to interpret as clisp infix or prefix constructs only those expressions that 
are specifically flagged аб such. Тһе user сап азо include  clisp declarations by — writing 
(CLISP declarations . form), eg, (CLISP (CLISP: FLOATING) ... ). These declarations will be 
used in place of any clisp declarations in the function definition. Note this feature provides a way of including clisp 
declarations in compiler macro definitions, 

65 CLISP translations can also be used to supply an interpretation for function objects, as well as forms, either for 

function objects that are used openly, i.e., appearing as car of form, function objects that are explicitly applyed, as 

with arguments to mapping functions, or function objects contained in function definition cells. In all cases, if car of 
the object is not LAMBDA or NLAMBDA, the interpreter and compiler will check clisparray. 

66 ғ the value of clispretranflg is T, dwimify will also (re)translate any expressions which have translations stored 

remotely. The initial value of clispretranflg is NIL. 


97 Note that the user can always | examine Ше translation | himself by performing 


(GETHASH expression CLISPARRAY). 
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If clisparray is NI | ‚58 translations are implemented instead by replacing the CLISP expression by 
an expression of the form (CLISP%_ translation . CLISP-expression),©? e.g., 
(FOR X IN Y COLLECT (CAR X)) would be replaced by 

(CLISPZ (MAPCAR Y (FUNCTION CAR)) FOR X IN Y COLLECT (CAR X)). Both the 
editor and prettyprint know about CLISP%_ expressions and treat them specially by suppressing 
the translations: Prettyprint prints just the CLISP (unless prettytranflg — T, as described below), 
while the editor makes the translation completely invisible, e.g., if the current expression were the 
above CLISP%_ expression, F MAPCAR would fail to find the MAPCAR, and (3 ON) would replace 
IN with ON, i.e., the editor operates as though both Ше CLISPZ and the MAPCAR were not there. 
As with translations implemented via clisparray, if the CLISP expression is changed by editing it, 
the translation is automatically deleted. | 


CLISP%_ expressions will interpret and compile correctly: CLISP%_ is defined as an nlambda 
nospread function with an appropriate compiler macro. Note that if the user sets clisparray to NIL, 
he can then break, trace, or advise CLISP%_ to monitor the evaluation of iterative statements, 
pattern matches, and record operations. This technique will work even if clisparray was not NIL at 
the time the expressions were originally translated, since setting clisparray to NIL will effectively 
delete the translations, thereby causing the CLISP expressions to be retranslated when they are first 
encountered. Note that if the user only wishes to monitor the CLISP in a certain function, he can 
accomplish this by embedding its definition in (RESETVAR CLISPARRAY NIL *). 


If а СІІ5Р% expression is encountered and clisparray is not NIL, the translation is transferred 
to the hash array, and the CLISP%_ expression replaced by just the CLISP. Setting prettytranflg 
to CLISP%_ causes prettyprint to print CLISP expressions that have been translated in the form of 
(CLISP% translation . CLISP-expression), even if the translation is currently stored 
in clisparray. These two features together provide the user with a way of dumping CLISP 
expressions together with their translations so that when reloaded (and run or dwimified), the 
translations will automatically be transferred to clisparray. 


In summary, if prettytranflg  NIL, only the CLISP is printed (used for producing listings). If 
prettytranflg = T, only Ше translation is printed (used for exporting programs to systems that do not 
provide CLISP, and to examine translations for debugging purposes). ’ If prettytranflg=CLISP% , 
an expression of the form (CLISP%_ translation . CLISP) is printed, (used for dumping both 
CLISP and translations). The preferred method of storing translations is in clisparray, so that if 
any CLISPZ expressions are converted while clisparray 15 not NIL, they will automatically be 
converted so as to use clisparray. If clisparray - NIL, they will be left alone, and furthermore, new 
translations will be implemented using CLISP%_ expressions. 


68 clisparray is initially NIL, and #clisparray is its size. The first time a translation is performed, a hash array of this 


size is created. Therefore to disable clisparray, both it апа #clisparray should be set to NIL. 
69 CLISP%_ is an atom consisting of the six characters С, L, I, S, P, and space, which must be preceded by the escape 
character % in order for it to be included as a part of an identifier. The intent was to deliberately make this atom 
hard to type so as to make it unlikely that it would otherwise appear in a user's program or data, since the editor 
and prettyprint treat it very specially, as described above. 
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Note that makefile will reset prettytranflg to T, using resctvar, when called with the option NOCLISP, 
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23.10 DECLARATIONS 


. Declarations are used to affect the choice of Interlisp function used as the translation of a particular 


operator. For example, A+B can be translated as either (IPLUS A B), (FPLUS A B), or 
(PLUS A B), depending on Ше declaration in effect. Similarly Х:1«Ү can mean © 
(RPLACA X Y), (FRPLACA X Y), ог (/RPLACA X Y), and <!!А B> сег (NCONC1 А B) 
or (/NCONC1 A B). The table below gives the declarations available in CLISP, and the Interlisp 
functions they indicate. The choice of function on all CLISP transformations are affected by these | 
declarations, i.e, iterative statements, pattern matches, record operations, as well as infix and prefix 
operators. 


The user can make (change) a global declaration by calling the function CLISPDEC and giving it 
as its argument а list of declarations, е.р., (CLISPDEC (QUOTE (FLOATING UNDOABLE)) ). 
Changing a global declaration does not affect the speed of subsequent CLISP transformations, since 
АП CLISP transformation are table driven (ie. property list), and global declarations are 
accomplished by making the appropriate internal changes to CLISP at the time of the declaration. 
If a function employs /оса! declarations (described below), there will be a slight loss in efficiency 
owing to the fact that for each CLISP transformation, the declaration list must be searched for 
possibly relevant declarations. | 


Declarations are implemented in the order that they are given, so that later declarations override 
earlier ones. For example, the declaration FAST specifies that FRPLACA, FRPLACD, FMEMB, 
and FLAST be used in place of RPLACA, RPLACD, MEMB, and LAST; the declaration RPLACA 
specifies that RPLACA be used. Therefore, the declarations (FAST RPLACA RPLACD) will cause 
FMEMB, FLAST, RPLACA, and RPLACD to be used. 


The initial global declaration is INTEGER and STANDARD. 


TABLE OF DECLARATIONS 


| Declaration | Interlisp functions to be used 

INTEGER or FIXED IPLUS, IMINUS, IDIFFERENCE, ITIMES, IQUOTIENT, 
ILESSP, IGREATERP | | 

FLOATING FPLUS, FMINUS, FDIFFERENCE, FTIMES, FQUOTIENT, 
LESSP, FGTP 

MIXED | PLUS, MINUS, DIFFERENCE, TIMES, QUOTIENT, LESSP, 
GREATERP | 

ҒА5Т FRPLACA, FRPLACD, FMEMB, FLAST, FASSOC 

UNDOABLE /RPLACA, /RPLACD, /NCONC, /NCONC1, =/MAPCONC, 
/MAPCON 

STANDARD RPLACA, RPLACD, MEMB, LAST, ASSOC, NCONC, МСОМС1, 
MAPCONC, MAPCON 

__ВРЦАСА, RPLACD, corresponding function 

/RPLACA, ... | 
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The user can also make declarations affecting a selected function or functions by inserting ап 
expression of the form (CLISP: . declarations) immediately following the argument list, i.e., as 
CADDR of the definition. Such local declarations take precedence over global declarations. 
Declarations affecting selected variables can be indicated by lists, where the first element is the 
name of a variable, and the rest of the list the declarations for that variable. For example, 
(CLISP: FLOATING (X INTEGER)) specifies that in this function integer arithmetic be used 
for computations involving X, and floating arithmetic for all other computations./! The user can 
also make local record declarations by inserting a record declaration, e.g., (RECORD --), 
(ARRAYRECORD --), etc., іп the local declaration list. Local record declarations override global 
record declarations for the function in which they appear. Local declarations can also be used to 
override the global setting of certain DWIM/CLISP parameters effective only for transformations 
within that function, by including in the local declaration an expression of the form 
(variable = value), e.g., (PATVARDEFAULT = QUOTE). 


The CLISP: expression is converted to a comment of a special form recognized by CLISP. 
Whenever a CLISP transformation that is affected by declarations is about to be performed in a 
function, this comment will be searched for a relevant declaration, and if one is found, the 
corresponding function will be used. Otherwise, if none are found, the global declaration(s) 
currently in effect will be used. 


Local declarations are effective in the order that they are given, so that later declarations can be 
used to override earlier ones, e.g., (CLISP: FAST RPLACA RPLACD) specifies that FMEMB, 
FLAST, RPLACA, and RPLACD be used. An exception to this is that declarations for specific 
variables take precedence of general, function-wide declarations, regardless of the ШК of 
appearance, as in (CLISP: (X INTEGER) FLOATING). 


Clispify also checks the declarations in effect before selecting an infix operator to ensure that the 
corresponding CLISP construct would in fact translate back to this form. For example, if a 
FLOATING declaration is in effect, clispify will convert (FPLUS X Y) to X+Y, but leave 
(IPLUS X Y) as is. Note that if (FPLUS X Y) is CLISPIFYed while a FLOATING declaration 
is under effect, and then the declaration is changed to INTEGER, when Х+Ү is translated back to 
Interlisp, it will become (IPLUS X Y). 


23.11 THE RECORD PACKAGE? 


The advantages of "data-less" or data-structure-independent programming have long been known: 
more readable code, fewer bugs, the ability to change the data structure without having to make 
major modifications to the program, etc. The record package in CLISP both encourages and 
facilitates this good programming practice by providing a uniform syntax for creating, accessing and 
storing data into many different types of data structures, e.g. those employing arrays, list structures, 
association lists, hash links, etc., and combinations thereof, as well as removing from the user the 


n "involving" means where the variable itself 5 ап operand. For example, with the declaration 
(FLOATING (X INTEGER)) in effect, (FOO Х)Ч(ЕТЕ X) would translate to FPLUS, i.e., use floating arithmetic, 
even though X appears somewhere inside of the operands, whereas X+(FIE X) would translate to IPLUS. If there 
are declarations involving both operands, e.g., X*Y, with (X о, (Ү INTEGER), whichever appears first 
in the declaration list will be used. 

72 


The record package was written by L. M. Masinter. 
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task of writing the various routines themselves. The user declares (once) the data structure(s) used 
by his programs, and thereafter indicates the manipulations of the data in a data-structure- | 
independent manner. The record package automatically computes from the declaration(s) the 
corresponding Interlisp expressions necessary to accomplish the indicated access/storage operations. 
The user can change his data structure simply by changing the corresponding аа апа 
his program automatically (re)adjusts itself to the new conventions. 


The user informs the record package about the format of his data structures by making a record 
declaration. A record declaration defines a record, i.e., a data structure. The record declaration is a 
description of the record, associating names with its various parts, or fields. For example, the 
record declaration (RECORD MSG (ID (FROM TO) . TEXT)) describes a data structure called 
MSG, which contains four fields: ID, FROM, TO, and TEXT. The user can then reference these 


fields by name, either to retrieve their contents or to store new data into them, by using the : 


operator followed by the field name. For example, for the above record declaration, X: FROM 
would Бе equivalent (and , translate) to (CAADR X), and Y:TO+Z to 
(CAR (RPLACA (CDADR Y) Z) ).? Record operations are implemented by replacing expressions 


of the form Х:ЕОО by (fetch FOO of X), and X:FOO¢Y by (replace FOO of X with Y) 


and then storing the translation elsewhere, usually in a hash array, as described on page 23.22. 
CLISP also recognizes expressions input in this form; both lower and upper case are acceptable./^ - 


The fields of a record can be further broken down into sub-fields by subdeclarations within the 
record, e.g., 

(RECORD NODE (POSITION . LABEL) (RECORD POSITION (XLOC . YLOC))) 
would permit the user to refer to POSITION, or to its subfields XLOC and YLOC. | 


Note that what the record declaration is really doing is specifying the data-paths of the structure, _ 
and thereby specifying how the corresponding access/storage operations are to be carried out. For | 
example, the above declaration of NODE says the XLOC of a NODE is to be found as the CAR of its 
POSITION, which is the CAR of the NODE itself. Hence, №: XLOC*30 is achieved by performing | 
(CAR (RPLACA (CAR N) 30)). | 


Note also that when the user writes №: XLOC, he is implicitly saying the N is an instance of the 
record NODE, ог at least is to be treated as such for this particular operation. In other words, the - 
interpretation of М: field never depends оп the value of N. The record package does not provide 
any facility which uses run-time checks to determine data paths, nor is there any error checking 
other than that provided by Interlisp itself. For example, if N happened to be an array, N: YLOC 
would still compute (СОАК М). 


The user can also create new data structures using a record declaration as a guide or template. 
Initial values for the contents of each field can be specified in the CREATE expression, defaulted to 
values specified in the record declaration, or CREATE can be instructed to use an existing datum as 
a model, i.e. to obtain the field values for the new datum from the corresponding fields of an 


n or /RPLACA or FRPLACA, depending оп the CLISP declaration in effect. Note that the value of X: ТОе7 is Z. In 


general, the value of a replacement record operation is the same as the value stored into the field. In this case, the 
. Interlisp-10 compiler will eliminate the CAR if the value of X: TO«Z is not actually used, e.g. if the replacement is a 
Statement іп a PROG. 


7 үр ETCH and FREPLACE are versions which insure FAST CLISP declarations will be in effect, /REPLACE insures 
UNDOABLE declarations, e.g. using the declaration for the record MSG shown above, (FREPLACE TO OF Y WITH 
2) would translate as (CAR (FRPLACA (CDADR Y) Z)). and eee TO OF Y WITH Z) would use 
/ RPLACA. 
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existing datum. For example, with the above declaration oof МОРЕ, 


(CREATE NODE USING FOO XLOC«10 LABEL©«'L1) translates to 


(CONS (CONS 10 (CDAR FOO)) (QUOTE L1)). 


The record package also provides a facility for allowing the user to test if a datum is an instance of 
a given record via a TYPE? expression, as explained below. | 


RECORD (used to specify elements and tails of а list structure) is just one of several record-types 
cutrently implemented. For example, the user can specify a property list format by using the 
record type PROPRECORD, or that ficlds are to be associated with parts of the data structure via 
hash links by using the record-type HASHLINK, or that an entirely new data type be allocated (as 
described in section 3) by using the record-type DATATYPE. These are described 1 in detail below. 


As with all DWIM/CLISP facilities, the record package contains. many ibid [йаш features, 
spelling correction on field names, record types, etc. In addition, the record package includes a 
RECORDS file package command for dumping record declarations,? as well as the appropriate 


modifications to the file package (Section ii so that files? and cleanup will inform the user about _ 


records that need to be dumped. 


RECORD DECLARATIONS 


А record declaration is an expression of the form 
(record-type record-name fields . {record tail}) 
This expression is evaluated to effect the corresponding declaration.76 


l. record-type specifies the "type" of data being described by the record declaration, and thereby | 


implicitly specifies the data paths, Те. how the corresponding access/storage operations аге 
performed. record-type currently is either RECORD, TYPERECORD, ARRAYRECORD, 
ATOMRECORD, ASSOCRECORD, PROPRECORD, DATATYPE, HASHLINK, ARRAYBLOCK or 
ACCESSFNS. RECORD and TYPERECORD are used to describe list structures, DATATYPE to 
describe user data-types, ARRAYRECORD to describe arrays, ATOMRECORD to describe (the 

property list of) atoms, PROPRECORD to describe lists in property list format, and 
ASSOCRECORD to describe association list format. HASHLINK can be used with any type of 
data: it simply specifies the data path to be a hash-link. ACCESSFNS is also type-less; the user 
specifies the data-paths in the record declaration itself, as described below. 


2. record-name is a literal atom used to identify the record declaration for dumping to files via 
the RECORDS file package command, creating instances of the record via CREATE, and testing 


via ТҮРЕ?. DATATYPE and TYPERECORD declarations also use record-name to identify the 


75 тре file package command INITRECORDS can be used to write expressions on a file that will, when loaded, perform 
whatever initialization/allocation is necessary for the indicated records, but not to write out, and hence cause to be 
read back in, the record declarations themselves. This facility is useful for building systems on top of Interlisp, in 
which the implementor may want to eliminate the record declarations from a production version of the system, but 
the initialization for these records must still be done. 

76 


Local record declarations are performed by including an expression of this form in the CLISP declaration for that 
function (page 23.25), rather than evaluating the expression itself. 
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data structure (as described below). Ш 


Бог. subdeclarations, record- -name пеша Ше parent field that is beme elaborated. 


fields describes Tm structure of the record. Its exact чийе Он varies with the record-type: 


RECORD fields is a list structure whose non-NIL literal atoms are taken as field-names 
to be associated with the corresponding elements and tails of a list structure. 
NIL сап be used as a place marker to fill an unnamed field, e.g, (A NIL В) 
describes a three element list, with B corresponding to the third element. A 
number may be used to indicate a sequence of NI ILs, e 5. (А 4 В) 15 
interpreted as (A NIL NIL NIL NIL В). ! 


TYPERECORD Similar to RECORD except that особ паа is also used as an indicator in 
CAR of the datum to signify what "type" of record it is. CREATE will insert 
an extra field containing record-name at the beginning of the structure, and 
the translation of the access and storage functions will take this extra field into 
account./8 For ‘example, for 
(TYPERECORD MSG (ID (FROM TO) . TEXT)), X:FROM translates аз 
(CAADDR X), not (CAADR X). | 


ASSOCRECORD fields is а list of literal atoms. The fields are stored іп a-list format: i.e., 
((fieldname . value) (fieldname . value) ..). Accessing is performed with 
assoc,” storing with putassoc. IN m 


PROPRECORD fields is a list of property names. The fields are stored in "property list” 
format; i.e., (fieldname value fieldname value . ..). Accessing is performed with 
listget, storing with listput. Both ASSOCRECORD and PROPRECORD are useful 
for defining data structures in which it is often the case that many of the 
fields are NIL. A CREATE for these и types only stores those fields which 
are non-NIL. 


ARRAYRECORD fields is a list of ficld-names that are associated with the РИТ ТЕ 
-= elements of the array. NIL can be used as a place marker for an unnamed 

field (element). Positive integers can be used as abbreviation for the 

corresponding number of NILs. For example, (ARRAYRECORD (ORG 

DEST NIL ID 3 TEXT)) describes an eight element array, with ORG 

corresponding to the first element, ID to the fourth, and TEXT to the eighth. 


HASHLINK fields is either just field-name, іе. an atom, or a list interpreted as 


For some top-level declarations, record-name is optional, e.g., (RECORD (ID (FROM ТО) . TEXT)) is 
acceptable. However, if record-name is omitted, the user cannot specify the record by name, e.g, in CREATE 
expressions, or when using the RECORDS file package command. 


This type-field is used by the record package in the translation of TYPE? expressions. 
or fassoc, depending on current CLISP declarations. 


However, with the declaration (PROPRECORD FIE (H I J)) the expression (CREATE FIE) would still construct 
(Н NIL), since a later operation of X: ЈЄТ could not possibly change the instance of the record if it were NIL. 
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(ficld-name array name arraysize). arrayname indicates the hash-array to be 
used; if not given, SYSHASHARRAY 15 used. For example, 


(HASHLINK (CLISP CLISPARRAY)) would permit the user to Obtain the 
CLISP translation of X by simply writing X:CLISP. arraysize is used for 
initializing the hash array: if arrayname has not been initialized at the time of 
the declaration, it will be | sett Юю 


(LIST (HARRAY (OR arraysize 100))). HASHLINKs are useful as 


subdeclarations to other records to add additional fields to already existing 
data-structures. 


specifies that a new user data type with type name record-name be allocated 


via declaredatatype (see Section 3).81 When a DATATYPE declaration is given | 
for the first time, the system allocates storage space and а type number (ог | 
that data type. Thus, unlike other record-types, the records of а DATATYPE _ 


declaration are represented with a completely new Interlisp type, and not in 
terms of other existing types.8* fields 15 а list of field specifications, where 


each specification is either fieldname ог (ће пате fieldtype). If fieldtype іѕ 


omitted (or fieldtype = POINTER) then the field can contain a pointer to any 
arbitrary Interlisp datum. Other options for fieldtype are: 


BITS n field contains an n-bit unsigned integer. 


BETWEEN n1 n2 a generalization of BITS. field may contain an 
integer x, such that x is greater than or equal to 


n1 and less than or equal to n2. Enough bits are | 


allocated to store a number between 0 and 
(n2-nl); nl is appropriatly added or попа 
when the field is accessed ог stored. | 


INTEGER or FIXP field contains a full word signed integer. 
FLOATING or FLOATP field contains a full word floating póint number. 
FLAG field is a one bit field that "contains" Т or NIL. 
For example, the declaration | 


(DATATYPE MSG ((FLG BITS 12) TEXT (CNT BETWEEN 10 25) 
HEAD (DATE BITS 18) (PRIO FLOATP) 
(READ? FLAG) ) ) 
would define a data type MSG which occupies (in Interlisp-10) three words of 
storage with two pointer fields (one word), a full word floating point number, 
fields for an 18, 12, and 4 bit unsigned integer, and a flag (one bit), with 1 bit 


Since the data type must be set up at run-time, the RECORDS file package command will dump a declaredatatype 
expression as well as the DATATYPE declaration itself. The INITRECORDS command will END only the 


declaredatetype expression. 


For this reason, DATATYPE declarations should be used with caution within local declarations, since a new and 
different data type is allocated for each one with a different name. 
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ей оуег. 3 


E ARRAYBLOCK similar to a DATATYPE declaration, except that the objects it creates and 


manipulates are arrays. As with DATATYPE’s, the actual order of the fields of 
the ARRAYBLOCK may be shuffled around in order to satisfy garbage collector 
constraints. 


For example, 


 (ARRAYBLOCK FOO ((F1 INTEGER) (F2 FLOATING) (ЕЗ POINTER) 
(FA BETWEEN -30 -2) (F5 BITS 12) 
(F6 FLAG) ) ) 


ACCESSFNS fields is a list of elements of the form (field-name accessdef setdef), i.e. for 


each fieldname, the user specifies how it is to be accessed and set. accessdef 
should be a function of one argument, the datum, and will be used for 
accessing. вейде 4 should be a function of two arguments, the datum and the 
new value, and will be used for storing. Alternatively, accessdef and/or setdef 
may be a LAMBDA expression or a form written in terms of variables DATUM 
and (in the case of setdef) NEWVALUE.9? For example, given the declaration 
ГАССЕ55ЕМ5 ( (FIRSTCHAR (NTHCHAR DATUM 1) 

(RPLSTRING DATUM 1 NEWVALUE)) 
(RESTCHARS (SUBSTRING DATUM 2] | | 

X:FIRSTCHAR*Y would translate to (RPLSTRING X 1 Y). Since по setdef 
is given for the RESTCHARS field, attempting to perform X: RESTCHARSeY 
would generate an error, REPLACE UNDEFINED FOR FIELD. Note that 
ACCESSFNS do not have a CREATE definition. However, the user may supply 
one in the {defaults and/or subdeclarations) of the declaration, as described 

below. Attempting to CREATE an ACCESSFNS record without specifying a 
create definition will cause an error CREATE NOT DEFINED FOR THIS | 
RECORD. 


ATOMRECORD fields is a list of property names, e.g., 


(ATOMRECORD (EXPR CODE MACRO BLKLIBRARYDEF)). Accessing is 
performed with getprop, storing with ршргор.“ 86 


In addition to the above built-in record types, users can declare their own record types by 
a performing the ш: steps: 


83 


84 


85 


86 


Fields are allocated in such a way as to optimize the storage used and not necessarily in the order specified. To store 
this ‘information in a _ conventional RECORD list structure, e.g., 
(RECORD MSG (FLG TEXT CNT DATE PRIO . HEAD)), would take 5 words of list space and up to three 
number boxes (for FLG, DATE, and PRIO). 


setdef may be omitted, in which case, no store operations are allowed. 


HÀ" patefecit 


ACCESSENS forms, eg [ACCESSFNS LITATOM ( (DEF (STANDARD GETD FAST FGETD) 
(STANDARD PUTD UNDOABLE /PUTD] means if FAST declaration is in effect, use FGETD for fetching, if 
UNDOABLE, use /PUTD for saving. 


as with ACCESSFNS, CREATE is not initially defined for ATOMRECORD records. 
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(1) add the new record-type to the value of clisprecordtypes:. 


(2) perform movd[RECORD;record-type], i.e. give the record-type Ше same definition as that of 


record: 


(3) put on the property list of the record-type, under the property USERRECORDTYPE, the 


name of a function which will return the translation. Whenever a record declaration of 


type record-type is encountered, this function will be passed the record declaration as its 
argument, and should return a new record declaration which the record package will then 
use in its place. 


{record-tail} is optional. It may contain expressions of the form: | 


(1) field-name + form allows the user to specify within the record declaration the 
default value to be stored in field-name by a CREATE (if no 
value is given within the CREATE expression itself). Note that 
form is evaluated at CREATE time, not when the declaration is 

made. 


(2) (CREATE form)? (re)defines the manner in which CREATE of this record should В 


Бе performed. This provides а way of specifying how 
ACCESSFNS should be created or overriding the usual 


definition of CREATE. If form contains the field-names of the | 
declaration as variables, the forms given іп the CREATE will be · 


substituted in. For example, 

(RECORD C (А. D)) and 

(ACCESSFNS C ((A CAR RPLACA) (D CDR RPLACD)) 
COREATELCONS A 0))) 

are equivalent.88 


If the word DATUM appears in the create form, the original 
create definition is inserted. This effectively allows the user to 
"advise" the create. 


(3) (INIT form) specifies that form should be evaluated when the record is 


87 CREATE may also be given as recordname © form, e.g. С < (CONS А 0). 


88 


possible representation of a data-structure is to store the fields in parallel arrays, especially if the number of instances 
required is known, and they do not need to be garbage collected. Thus, to implement a data structure called LINK 
with two fields FROM and TO, one would have two arrays FROMARRAY and TOARRAY. The representation of an 
"instance" of the record would be ап integer which is used to index into the arrays. This can be accomplished with 
the declaration: 
ГАССЕ55ҒМ5 LINK 
((FROM (ELT FROMARRAY DATUM) (SETA FROMARRAY DATUM NEWVALUE)) 
(TO (ELT TOARRAY DATUM) (SETA TOARRAY DATUM NEWVALUE))) 
(CREATE (PROG1 (SETQ LINKCNT (ADD1 LINKCNT)) 
(SETA FROMARRAY LINKCNT FROM) 
(SETA TOARRAY LINKCNT TO] 
To CREATE a new LINK, a counter is incremented and the new elements stored (although the create form given the 
declaration should actually include a test for overflow). 
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declared. 9? 


(4) а subdeclaration - i.e. а record declaration of any of the above types. The 
| | record-name of а subdeclaration must be either the гесогд-пате · 
of its immediately superior declaration or one of the superior’s 
field-names. Instead of identifying the declaration as with top. 
. level declarations, the record-name of a subdeclaration identifies | 
_ the parent field or record that is being described by the 
| subdeclaration. Subdeclarations can be nested to an arbitrary 
depth.” 


(5) (TYPE? form)? . (Re)defines the manner in which TYPE? expressions аге to be 
| | - translated. form may either be an expression in terms of 
DATUM or a function of one argument. 


(6) (SUBRECORD з name . гасу | | | | 
пате must Бе a field that appears in the current declaration 
and | the name of another record. This says that, for the 
purposes of create expressions, substitute the top-level 
-declaration of name for the SUBRECORD form, adding оп any 
| defaults specified. | 


For example: given (RECORD B (E F G)), then | 
(RECORD А (В С D) (SUBRECORD B)) would be treated 
like (RECORD A (B C D) (RECORD B (E F G))), for the 
purposes of translating CREATE пори. | 


СВЕАТЕ 


Record operations сап be applied to arbitrary structures, i.e., structures created directly by user 
programs can be manipulated in a data-independent manner using record declarations. However, to 
be completely data-independent, new data should be created using the same declarations that 
define its data paths. This can be done by means of an expression of the form 
(CREATE record-name . {assignments}). А CREATE expression translates into ап 
appropriate Interlisp form using cons, list, puthash, array, etc., that creates the new datum with the 


89 form will also be dumped by the INITRECORDS file package command. 


2 Note that, іп a few cases, it makes sense for а given field to have more than опе subdeclaration, For example, in 
(RECORD (А . В) (PROPRECORD В (FOO ЕТЕ FUM)) (HASHLINK B C)) 
B is elaborated by both a PROPRECORD and а HASHLINK. Similarly, 
(RECORD (A B) (RECORD A (C D)) (RECORD A (FOO FIE))) | 
is also acceptable, and essentially "overlays" (FOO ЕТЕ) and (C D), ie. Х:ЕОО and X:C would be equivalent. In - 
such cases, the first subdeclaration is the one used by CREATE. 
91 Giving (RECORD namel пате?) is a simple way of defining a synonym for the field namel, 
92 


TYPE? may also be given as record name @ form, e.g.C @ LISTP. 
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various fields initialized to the appropriate values. 93 ырш is optional and may contain 
expressions of the following form: 


field-name + form specifies initial wale for field-name.”4 
USING form specifies that for all fields not given a value by (1), the vae of 
the corresponding field in form is to be used. 
COPYING form like USING except the corresponding values are copied (with 
| copyall). 
REUSING form = like USING, except that wherever possible, the corresponding 


structure in form is used.?5 


SMASHING form a new instance of the record is not created at all; rather, the 
value of form is used and smashed. 


If the value of a field is neither explicitly specified, nor implicitly specified via USING, REUSING. 


or COPYING, the default value in the declaration is used, if any, otherwise NILÓFor example, 
following (RECORD A (B С D) D ~ 3), 

(CREATE A BeT USING X) translates as (LIST Т (CADR X) (CADDR Х)), 

(CREATE A B«T COPYING X)) as [LIST T(COPYALL (САВЕ Х)). (СОРУАЦ. 
(CADDR Х1, 

(CREATE А ВеТ REUSING Х) as (CONS Т (CDR X)), and 

(CREATE A BeT) as(LIST T NIL 3). 


TY PE? 


++ 


The record package allows the user to test if a given datum "looks like" an instance of a record. - 


9: CREATE is not defined as a function. Instead, DWIM calls the appropriate function in the record package giving it 
the entire CREATE expression as an argument. The translation of the CREATE expression, i.e., the Interlisp form 
which is evaluated to construct the datum, is then stored elsewhere, as with iterative statements and pattern matches. 

94 


The record package goes to great pains to insure that the order of evaluation in the translation is the same as that 
given in the original create expression if the side effects of one expression might affect the evaluation of another. For 
example, given the declaration (RECORD CONS (CAR . CDR)), the expression (CREATE CONS CDR*X САКФУ) 
will translate to (CONS Y X), but (CREATE CONS CDR+(FOO) CAR+(FIE) ) will translate to 

( (LAMBDA (551) (CONS (PROGN (SETQ $31 (Ғ00)) (FIE)) $$1))) 
because, for example, FOO might set some variables used by FIE. 


35 Note that (CREATE record REUSING form ...) does not itself do any destructive operations on the value of 
form. The distinction between USING and REUSING is that (CREATE record REUSING form ...) will 
incorporate as much as possible of the old data structure into the new опе being created, while 
(CREATE record USING form ...) will create a completely new data structure, with only the contents of the 
fields re-used. For example, CREATE REUSING a PROPRECORD just conses the new property names and values onto 
the list, while CREATE USING copies the top level of the list. Another example of this distinction occurs when a 
field is elaborated by a subdeclaration: USING will create a new instance of the sub-record, while REUSING will use 
the old contents of the field (unless some Пеја of the subdcclaration is assigned in the CREATE expression.) 


96 For BETWEEN ficlds in DATATYPE records, nl is used; for other non-pointer fields zero is used. 
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This сап be done ма an expression of the form (TYPE? record-name form). TYPE? is mainly 
intended for declarations involving record-type DATATYPE or TYPERECORD. For DATATYPES, the 
TYPE? check is exact; ie. the TYPE? expression will return non-NIL only if the value of form is 
an instance of the record named by record-name. For TYPERECORDs, the TYPE? expression on will 
check that the value of form is a list beginning with record-name. For ARRAYRECORDs, it checks 
that the value is an array of the correct size; For PROPRECORDs and ASSOCRECORDs, a TYPE? 
expression will make sure that the value of form is a property/association list with property names 
among the field- -names of the declaration, | 


Atrensiing to execute a TYPE? expression for a "— of type ACCESSFNS, HASHLINK or 
RECORD will cause an error, TYPE? NOT IMPLEMENTED FOR THIS RECORD. The user can 
(re)define the interpretation of TYPE? expressions for а particular declaration by inclusion of an 
expression of the form (TYPE? com) in the declaration, as described on page 23.32. | 


DATA-PATHS 


The user may also elaborate a field by declaring that field name in a separate. record declaration (as _ 
opposed to an embedded subdeclaration). For example, the declarations 

(RECORD MSG (ID (FROM TO) . TEXT)) and (RECORD TEXT. (HEADER . TXT)) | 
also subdivide TEXT into two subfields. The user may then specify X: MSG. HEADER to achieve the 
interpretation "X is а MSG, retrieve its HEADER".97 The notation X: МАМЕ1. МАМЕ2 is interpreted to 
mean "find а path from the record with name NAME1 to the field named NAME2", as opposed to 
| X: МАМЕ 1: NAME2, where NAME1 and МАМЕ2 are interpreted independently. „> · 


The central point of separate declarations is that the (sub)record is not tied to another — (as 


with embedded declarations), and therefore can be used in many different contexts. For example, je 


one might additionally have a declaration 
(RECORD REPLY (TEXT TO . RESPONSE) ). 

[n this case, one could specify X: REPLY.HEADER to mean that X is a REPLY, and to retrieve 
(CAAR X). In general, the user may "Deci as a data-path a chain of record/field names, e.g., 
X:MSG.TEXT.HEADER.SUBHEAD. .. еіс.,”9 where there is some path from each record to the 
next in the chain. Only as much ‘of the path as if"necessary to disambiguate it needs to be 
specified. For example, with the above declarations of MSG, TEXT and REPLY, the path 
X:MSG.HEADER is unambiguous (it must go through TEXT); however, X: TEXT is not, as this 
could mean that X is either a MSG or а REPLY.!9 Тһе record package interprets a data path by 
performing a tree search among all current declarations for a path from each name to the next, 
НВ first local declarations (if апу) апа then global ones. 


A^ 
за 


\ 
97 x : НЕАОЕК by itself is interpreted to mean that Х 15 an instance of TEXT, and translates as (CAR Х). 


98 Translation of expressions involving data paths are handled by replacing the expression by а fetch or replace 

. Statement with the fields given in a list; e.g, X:FOO.FIE.A and X:FOO.FIE.A«Y are replaced by the expression 

(fetch (FOO FIE A) X) and (replace (FOO FIE A) of X with Y) respectively, with the translation 
stored elsewhere. Input of this form is also acceptable. : 


99 Note that if a field has an identical interpretation in two declarations, e.g. if the field TEXT occurred in Ше same 
location within the declarations of MSG and REPLY, it would not be considered ambiguous. 


100 In this case, the message AMBIGUOUS RECORD FIELD is printed and an error is gencrated. If a data-path rather 
than a single ficld is ambiguous, (с.р... if there were усі another declaration (RECORD TO (NAME . HEADER)) and 
the user specified X:MSG.HEADER), the error AMBIGUOUS DATA PATH is generated, | 
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CHANGING RECORD DECLARATIONS 


The user may edit (or delete) global record declarations with the function 


editrec[editrecx] nlambda, nospread function, similar to editf or editv. editrec calls 


the editor оп a copy of all declarations in which car[editrecx] is the | 


record-name or a field name. On exit, it redeclares those that have 
changed and undeclares any that have been deleted. If car[editrecx] 
is NIL, all declarations are edited. 


Records can also be declared local to a particular function by using a CLISP declaration, as 
described on page 23.25; all local record declarations override global ones. In addition, a local 
declaration of the form (RECORDS A В С) is equivalent to having copies of the global declarations 
А, B, and С in the local declaration. 


For both global and local records, the translation is computed using all CLISP declarations in effect 
as described on page 23.24, e.g., if the declaration UNDOABLE is in effect, /RPLACA, /RPLACD, 
/PUTHASH, etc. will be used. 


When the user redeclares a global record, the translations of all expressions involving that record or 


any of its fields are automatically deleted 101 and thus will be recomputed using the new | 


information. If the user changes a local record declaration, or changes some other CLISP 


declaration, e.g., STANDARD to FAST, and wishes the new information to affect record expressions 


already translated, he must make sure the corresponding translations are removed, usually either by 
CLISPIFYING or applying the !DW edit macro. 

OTHER FUNCTIONS 

reclook[recordname;-;-;-;-] returns the entire declaration for the record named recordname. 


NIL if no record declaration with name гесогдпате.192 


fieldlook[fieldname] returns the list of declarations in which fieldname is the т name of a 
field. 


recordfieldnames[recordname] returns the list of fields declared in record recordname, гесогапате 


may either be a пате or ап entire declaration. 


101 гол clisparray. If the user is not using this method for storing translations, i.e., is instead using Ше СІЛ5Р% 


те од (page 23.23), those expressions already translated will remain as they are. (There is no practical way to locate 
them.) 
102 Note that the record package maintains internal state about current record declarations; performing destructive 
opcrations (e.g. nconc) on the value of reclook may leave the record package in an inconsistant state. To change a 
record delcaration, use editrec. 
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recordaccess[ficld;value;type;newvalue;dec] TE | 

type is one of (FETCH FFETCH REPLACE  FREPLACE 
/REPLACE) or their lowercase equivalents. type=NIL means 
FETCH. If type corresponds to a fetch operation, i.e. is FETCH, or 
FFETCH, recordaccess performs (type field OF value) If type 
corresponds to a replace, recordaccess performs (type field OF value 
WITH newvalue). dec is an optional declaration; if given, field is 
interpreted as a field name of that declaration. 103 


23.12 CHANGETRAN 


A very common programming construction consists of assigning a new value to some datum that is 
a function of the current value of that datum. Some examples of such read-modify-write sequences 
include: 


(SETQ X (IPLUS X 1)) _Incrementing a counter 
(SETQ X (CONS Y X)) Pushing an item on the front of a 
 (PROG1 (CAR X) (SETQ X ( CDR Х))) Popping ап item off a list 


It is easier to express such computations shen the datum in question is a simple variable as above 
than when it is an element of some larger data structure, for instance, the car of some list: 


(RPLACA Х (IPLUS (CAR X) 1)) 
(RPLACA X (CONS Y (CAR X)) 

(PROG1 (CAAR X) (RPLACA X (CDAR X))) 
(SETA A N (IPLUS (ELT A М) 1))) 


The difficulty in expressing (and reading) modification idioms is in part due to the well-known 


.assymmetry of smashing versus accessing operations on structures: rplaca is used to smash what car 


would return, seta corresponds to elt, and so on. The CLISP operator * and the record package : 
operator combine to provide a more uniform mode of expression: 


X:1 є (IPLUS X:1 1) 
3:1 е (CONS Y X:1) 
(PROG1 (CAR X:1) (X:1 + (сов X:1))) 


The ¢ operator also helps in the seta-elt example, because elt and seta are defined to Бе. 
setfn-accessfn pairs: | | 


(ELT A N) e (IPLUS (ELT A N) 1) 


CLISP allows the same expression to be used for both the accessing and the smashing components 
of these statements, but it is still not obvious that they all involve a simple notion of structure 
modification. The user must read these statements very carefully to notice that the X:1 and 
(ELT A М) expressions appear twice (с.р., the second expression might have been (ELT А M)), 


103 Note that recordaccess is relatively inefficient, although it is better than constructing the equivalent form and 
performing an EVAL. 


m Changctran was ; designed by R. M. Kaplan. 
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and he must type (and edit) the same expressions twice, which can be cumbersome if the 
expressions are large. 


The Changetran facility is designed to provide a more satisfactory notation in which to express 
certain common (but user-extensible) structure modification operations. Changetran defines a set 
of CLISP words that encode the kind of modification that is to take place, e.g. pushing on а list, 
adding to a number, etc. More important, the expression that indicates the datum whose value is 
to be modified needs to be stated only once. Thus, the "change word" ADD is used to increase the 
value of a datum by the sum of a set of numbers. Its arguments are an expression denoting the 
datum, and a set of items to be added to its current value. For example, (ADD X:3 (Ғ00)) is 
equivalent to X:3¢X:3+( FOO). | 


The datum expression in this and all other changewords must be an expression that can appear to 
the left of the CLISP « operator, e.g. a variable, а: expression, an accessfn form, or any of the 
corresponding dwimified expressions fetch, CAR, LAST, etc, e.g. (ADD (ELT A М) 1). For 
ADD and for all other changewords, the lower-case version may also be specified. Except for POP 
(see below), the value of all built-in changeword forms is defined to be the new value of the 
datum. Finally, if the datum expression is a complicated form involving subsidiary function calls 
(eg. (ELT (FOO X) (FIE Y))), changetran goes to some lengths to make sure that those 
subsidiary functions are evaluated only once (it binds local variables to save the results), even 
though they logically appear in both the setting and accessing parts of the translation. Thus, in 
thinking about both efficiency and possible side effects, the user can rely on the fact that the forms 
will be evaluated only as often as they appear in the a | 


+ + + + + + + + + + + + + + + + + + + ++ 


СНАМСЕ WORDS RECOGNIZED BY CHANGETRAN 

The following is a list of those change words recognized by changetran 

(ADD datum item; item, ..) Adds the specified items to the current value of the datum, stores 
the result back in the datum location.” | 

(PUSH datum item, item» ...) Conses the items onto the front of the current value of the datum, 
and stores the result back in the datum location. Equivalent to 
(даште «item; item» ... ! datum >). | For example 
(PUSH X A B) would translate as 
[SETQ X (CONS A (CONS B X]. | 

(PUSHNEW datum item) Like PUSH (with only one item) except that the item 15 not added if 
it is already fmemb of Ше datum’s value." 

(PUSHLIST datum item; item» ... | 
Similar to PUSH, except that the items are appended in front of the 
current value of the datum. Equivalent to 
(datum + <! item; ! item, ... ! datum >). 


+ + + + ++ + + + + + ++ + + 


105 The translation will изе IPLUS, PLUS, ог FPLUS according to Ше CLISP declarations in effect. 


106 Note that, whereas [CAR (PUSH X "ЕООЈ will always be FOO, [CAR (PUSHNEW X 'FOO] might be somcthing 
else if FOO alrcady existed in the middle of the list. | 
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(POP datum) . . . . Returns car of the current value of the datum after stoning its cdr 
| into the datum. Equivalent to | 
[PROG1 (CAR datum) (datum * (CDR datum]. 
"The current value is computed only once even though it is 
referenced twice. Note that this is the only built-in changeword for 
which the value of the form is not the new value of the datum. 


(SWAP forml form2). | sets forml to form2 and vice versa, ie. is equivalent to 
(forml -(PROG1 form? form2 є form1)), except that саге is taken to 
make sure that expressions are not reevaluated unnecessarily. 


(CHANGE datum form) This is the most flexible of all change words, since it enables the 
| . user to provide an arbitrary form describing what the new value | 
should be, but it still highlights the fact that structure modification — 

is to occur, and still enables the datum expression to appear only 

once. (CHANGE datum form) is equivalent to (datum * form’), 

where form’ is constructed from the form in the CHANGE statement 

by substituting the datum expression for every occurrence of the. 

atom DATUM. For example, (CHANGE Х:ЕОО (DATUM*5)) is 

equivalent to (X:FOO « (ITIMES X:FOO 5)). CHANGE is useful 

for expressing modifications that are not built-in and are not 

sufficiently common to justify defining a user-changeword. As for 
other changeword expressions, the user need not repeat the datum-- 

expression and need not worry about multiple evaluation of the 
accessing form. | | 


23.13 CLISPIFY 


 Clispify converts Interlisp expressions to CLISP. Note that the expression given to clisp ify need 


not have originally been input as CLISP, i.e., clispify can be used on functions that were written 


© before CLISP was even implemented. Clispify is cognizant of declaration rules as well as all of the © 


precedence rules. For example, clispify will convert (IPLUS A (ITIMES В C)) into A+B*C, 
but (ITIMES A (IPLUS B C)) into А" (В+С).08 Clispify converts calls to the six basic 
mapping functions, MAP, MAPC, MAPCAR, MAPLIST, MAPCONC, and MAPCON, into equivalent 
iterative statements. 1t also converts certain easily recognizable internal PROG loops to the 

corresponding i.s. For example, | | 


... label (COND (pred ... forms ... (GO label))) ... 
becomes | | 
... label (WHILE pred DO ... forms ...) ... 109 


107 clispify is table driven exactly the same as CLISP, so that if the user changes any precedence, or defines new 


operators, clispify "automatically" knows about it. 


108 clispify also knows how to handle expressions consisting of a mixture of Interlisp and CLISP, e.g., (IPLUS A B*C) 
. is converted to A+B*C, but (ITIMES A B+C) to аа» clispify handles such cases by first dwim nilying the 
expression. 


clispify can convert all iterative statements input in CLISP back to CLISP, regardless of how complicated the 
translation was, because the original CLISP is saved. | 
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Clispify is not destructive to the original Interlisp expression, ie. clispify produces а new 
expression without changing the original. 10 Clispify will not convert expressions appearing as 
arguments to NLAMBDA functions," 

The value of various global parameters affect the operation of clispify: 


cl:flg 


The user can disable the : transformation by setting the variable с: Пр to NIL. This will prevent | 


clispify from constructing any expression employing a : infix operator, е.р., (CADR X) will not be 
transformed to X: 2. When cl:flg is T, clispify will convert to : notation only when the argument is 


atomic or a simple list (a function name and one atomic argument). If cl:flg is ALL, clispify will P 


convert to : expressions whenever possible. The initial value of cl:flg is Т. 


clremparsflg 


Clispify will remove parentheses in certain cases from simple forms, where "simple" means a 


function name and one or two atomic arguments. For example, (COND ((ATOM X) --)) will 
CLISPIFY to (IF АТОМ X THEN --). However, if clremparsflg is set to NIL, clispify will 


produce (IF (ATOM X) THEN --). Note that regardless of the Setting of this flag, the 
expression can be input in either form. The initial value of clremparsflg is Т. | 


clispifypackflg 
clispifypackflg affects the treatment of infix operators with atomic operands. If clispifypackflg is Т, 


clispify will pack these into single atoms, e.g, (IPLUS A (ITIMES В С)) becomes A+B*C. ТЕ 


clispifypackflg is NIL, no packing is done, e.g., the above becomes А + В * С. The initial value 
of clispifypackflg is T. 


. clispifyenglshflg 


If T, causes clispify to convert LISP forms to english phrases when possible, e.g., (MEMBER X Y) 
-» X IS A MEMBER OF Y.. See page 23.21. 


funnyatomlst 


Suppose the user has variables named А, В, and A*B. ІҒ clispify were to convert 
(ITIMES A В) to A*B, A*B would not translate back correctly to (ITIMES A В), since it would 
be the name of a variable, and therefore would not cause an error. The user can prevent this from 
happening by adding АВ to the list funnyatomlst. Then, (ITIMES A B) would clispify to 
А * B. | 


Note that A*B's appearance on funnyatomlst would not enable DWIM/CLISP to decode A*B+C аѕ 


110 The new expression may however contain some "pieces" of the original, since clispify attempts to minimize the 


number of CONSes by not copying structure whenever possible, 
11 Except for those functions whose INFO property is or contains the atom EVAL, such as nlsctq, resetlst, etc. clispify 
also contains built in information enabling it to process special forms such as prog, selcctq, etc. If the INFO 
property is or contains the atom LABELS, clispify will never create an atom (by packing. at the top level of the 
expression. For example, prog is handled in this fashion, 
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(IPLUS A*B C); funnyatomlst is used only by clispify. Thus, if an identifier contains a CLISP 


character, it should always be separated (with spaces) from other operators. For example, if X* is a 
variable, the user should write (SETQ X* form) іп CLISP as X* «form, not X* eform. However, 
in general, it is best to avoid use o = identifiers containing СЫРЁ — character operators а: as much as 


possible. 


clispifyprettyflg 


If T, causes prettyprint to clispify all expressions before printing them (but not to redefine any 
functions). clispifyprettyflg is temporarily reset to T, using гезефуаг, when makefile is called with 
the option CLISPIFY, or when the file in question has property FILETYPE with : with value CLISP on 
its property list. clispifyprettyflg is initially NIL. 


In addition to the above controls, disabling a CLISP сх, (ѕее cldisable, page 23 59) will ја 
disable the corresponding CLISPIFY transformation. Thus, if ¢ is is “turned off", AB will not 
апо (о а А В), nor vice versa. 


clispifyuserfn | 


ЈЕ Т, causes dispifyuserfn, a function of one argument, to be called on the form (list) to te 
clispified, when form is not otherwise recognized by clispify. If a non-NIL value is returned, this 
value is treated as the clispified version of the form. 


23. 14 DWIMIFY 


Dwim ify is effectively: a preprocessor for CLISP. wimify operates by scanning an expression as 
though it were being interpreted, and for each shy ia would generate an error, calling DWIM to 
"fix" it2 Thus the user will see the same messages, and be asked for approval in the same 
ш as he would if the expression were actually run. If DWIM is unable to make. | a 
correction, no message is printed, the form is left as it was, and the Е proceeds. 


Dwimify knows exactly how the interpreter works. It knows. the syntax of progs, selectas, lambda 
expressions, setqs, et al. It knows that the argument of nlambdas are not evaluated. ^ It also 
knows how variables are bound.!l^ In the course of its analysis of a particular expression, dwimify 
builds a list of the bound variables from the LAMBDA expressions and PROGs that it encounters. It 
uses this list for spelling corrections. Dwimify also knows not to try to "correct" variables that are 
on this list since they would be bound if the expression. were actually being run. However, note 
that dwimify cannot, a priori, know about variables that are used freely but would be bound in a 
higher function if the expression were evaluated in its normal context. Therefore, dwimify will try 


12 Thus dwimify performs ай DWIM transformations, not just CLISP transformations, i.e., it does spelling correction, 


fixes 8-9 errors, handles F/L, etc. 
113 The user can inform dwimify that an NLAMBDA function does evaluate its arguments {presumably by direct calls to 
eval), by including on its property list the property INFO with value EVAL or a list which contains the atom EVAL. 


. The user сап inform dwimify that a particular function or construct binds variables by including the atom BINDS on 
the INFO property for car of the form. In this case, dwimify assumes that cadr of the form is the variable list, ie. a 
list of atoms, or lists of the form (var value). lambda, nlambda, prog, and resctvars are handled in this fashion. 
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to "correct" these уапађје 15 Similarly, dwimify will attempt to correct forms for which car is 
undefined, even when the form is not in error from the user's standpoint, but the corresponding 
function has simply not yet been defined. 


Dwimify will also inform the user when it encounters an expression with too many arguments,!6 . 
because such an occurrence, although does not cause an error in the Interlisp interpreter, 
nevertheless is frequently symptomatic of а parenthesis error, eg. the user wrote 
(CONS (QUOTE FOO X)) instead of (CONS (QUOTE FOO) X). Dwimify will print | 


POSSIBLE PARENTHESIS ERROR IN 
(QUOTE FOO X) 
TOO MANY ARGUMENTS (MORE THAN 1). 


dwimify will also check to see if а prog label contains a clisp character,” and if so, will alert the 
user by printing the message SUSPICIOUS PROG LABEL, followed by the label. The prog label 
will not be treated as clisp. | 


Note that in most cases, an attempt to transform a form that is already as the user intended will 
have no effect (because there will be nothing to which that form could reasonably be transformed). 
However, in order to avoid needless calls to DWIM or to avoid possible confusion, the user can 
inform dwimify not to attempt corrections or transformations, on certain functions or variables by 
adding them to the list nofixfnslst or nofixvarslst respectively.!! 


Dwimify and dwimifyfns (used to dwimify several functions) maintain two internal lists of those 
functions and variables for which corrections were unsuccessfully attempted. These lists are 
initialized to nofixfnslst and nofixvarslst. Once an attempt is made to fix a particular function or 
variable, and the attempt fails, the function or variable is added to the corresponding list, so that 
оп subsequent occurrences (within this call to dwimify or dwimifyfns), no attempt at correction is 
made. For example, if FOO calls FIE several times, and FIE is undefined at the time FOO is 
dwimified, dwimify will not bother with FIE after the first occurrence. In other words, once 
dwimify "notices" a function or variable, it no longer attempts to correct 11.120 Moreover, once 
dwimify "notices" such functions or variables, it subsequently treats them the same as though they 
were actually defined or set. 


H5 dwimify rebinds fixspelldefault to N, so that if the user is not at the terminal when dwimifying (or compiling), 
spelling corrections will not be performed. 

116 unless dwimcheck £ argsflg —NIL (initially T). 

n unless dwimcheckproglabelsflg =NIL (initially T), or the label is a member of nofixvarslst. 

118 мое that the user could achieve the same effect by simply setting the corresponding variables, and giving the- 
functions dummy definitions. 

119 Dwimify will never attempt corrections on global variables, i.e., variables that are a member of the list globalvars, or 
have the property GLOBALVAR with valuc T, on their property list. Similarly, Dwimify will not attempt to correct 
variables declared to bc LOCALFREEVARS or SPECVARS in block declarations or via DECLARE expressions in the 
function body. The user can also declare variables that are simply used freely in a function by using the USEDFREE 
declaration. | 

120 


Dwimify and dwimifyfns also "notice" free variables that are sct in the expression being processed. 
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Note that these internal lists are local to each call to dwimify and dwimifyfns, so that if a function 


containing Ғ000, a misspelled call to FOO, is dwimificd before FOO is defined or mentioned, if the 


function is dwimificd again after FOO has been defined, the correction will be made. 


Note that the user can undo selected transformations рене Бу dwim ify, as described in 


Section 22. 


COMPILING CLISP - 


Since the compiler does not know about CLISP, in order to compile functions containing CLISP 
constructs, the definitions must first be dwimified. The user can automate this process in several | 
ways: 


1) If the variable dwimifycompflg is T, the compiler will always dwimify expressions before 
си Шет. dwimifycompfig is initially NIL. 


2) Ifa file has the property FILETYPE with value CLISP on its property list, tcompl, bco mpl, | 


recompile, апа Ъгесотр е will operate as though dwimifycompflg is T and dwim imify а 
expressions before compiling. gnis 


3) ТЕ the function definition has а CLISP declaration (see page 23.24), including a null | 
declaration, ie, just (CLISP:), the definition will be automatically dwimified before 
compiling. | 


Note: compileuserfn (Section 18) is defined to call dwimify on iterative statements, IF-THEN 
statements, and fetch, replace, and match expressions, i.e., any CLISP construct which can Бе 
recognized by its car of form. Thus, if the only CLISP constructs in a function appear inside of 


iterative statements, IF statements, etc., the function does not have to be dwimified before 


compiling. 


If dwimify is ever unsuccessful in processing a CLISP expression, it will E the error message 
UNABLE TO DWIMIFY followed by the expression, and go into а break.!? The user can then 
either: | 


(1) type OK to Ше break, which will cause the compiler to try again, e. 8. the user could define 
some missing records while in the break, and then continue; or 


" type f, which will cause the compiler to simply compile the expression as is, i.e. as though: clisp 


had not been enabled in the first place; Or 
(3) return an expression to be compiled in its place by using the RETURN break command. 


Note: tcompl, bcompl, recompile, and brecompile all scan the entire file before doing any 


121 unless dwimessgag — T. In this case, the expression is just compiled as is, i.e. as though clisp had not been enabled. 
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compiling, and take note of the names of all functions that are defined in the file as well as the 
names of all variables that are sct by adding them to nofixfnslst and nofixvarslst, respectively. 


. Thus, if a function is not currently defined, but із defined in the file being compiled, when 


dwimify is called before compiling, it will not attempt to interpret the function name as CLISP 
when it appears as car of a form. Dwimify also takes into account variables that have been 
declared to be GLOBALVARS, LOCALVARS, or SPECVARS, either via block declarations or 
DECLARE expressions in the function being compiled, and does not attempt spelling correction on 
these variables. The declaration USEDFREE is also available to declare variables simply used freely 
in a function. These variables will also be left alone by dwimify. Finally, nospellflg (see page 
23.57) is reset to T when compiling functions from a file (as opposed to from their in-core 
definition) so as to suppress spelling correction. 


23.15 THE PRINTOUT PACKAGE 


Interlisp provides many facilities for controlling the format of printed output. By executing various 
sequences of prinl, prin2, tab, terpri, spaces, printnum, and printdef, almost any effect can be 
achieved. Тһе printout package implements a compact language for specifying complicated 
sequences of these elementary printing functions. It makes fancy output formats easy to design 
and simple to program. | 


OVERVIEW AND EXAMPLES 


PRINTOUT is a CLISP word (like for and if) for interpreting a special printing language in 
which the user can describe the kinds of fancy printing he wants to achieve. The description is 
translated by dwimify machinery to the appropriate sequence of prinl, tab, etc. before it is 
evaluated or compiled. Printout printing descriptions have the following general form: 


(printout file printcom; printcom, ... printcom,) | 


The file parameter is evaluated to obtain the name of the file to which the output from this 
specification is directed, and each printcom in the sequence is a command that indicates a printing 
event to be executed. The various ways of realizing a printcom are defined below. The following 
examples give a general flavor of how printout is used. 


Example 1: Suppose the user wanted to print out on his terminal the values of three variables, x, 
y, and 2, separated by spaces and followed by a carriage return. This could be done by: | 


(PRIN1 X T) 

(SPACES 1 T) 
(PRIN1 Y T) 

(SPACES 1 T) 
(PRIN1 Z T) 

(TERPRI T) 


or by the more concise printout form: 

(PRINTOUT TX , Y , Z T) 
Here the first T specifies output to the terminal, the commas cause single spaces to be printed, and 
the final T specifies a terpri. The variable names are not recognized as special printout commands, 


so they are printed using prinl by default. 
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Example 2. Suppose the values of x and у are to be pretty-printed lined up at position 10, 
preceded by identifying strings. If the output is to go to the primary output file, the user could 
write either: 


(PRIN1 "X =") 
(PRINTDEF X 10 T) 
(TERPRI ) 

(PRIN1 "Y =") 
(PRINTDEF Y 10 T) 
( TERPRI) 


or the equivalent: 
(printout NIL "X =" 10 .PPV X T "Y =" 10 .PPV Y T) 


Since strings are not recognized as special commands, "X =" is also printed with prinl by default. 
The positive integer means tab to position 10, where the . PPV command causes the value of x to 
be prettyprinted as a variable. By convention, special atoms used as printout commands are 
prefixed with a pene’ The T causes a carriage return, so the y information is printed on the next 
line. 


Example 3. As a final example, suppose that the value of x is an integer and the value of y is a 
floating-point number. x is to be printed right-flushed in a field of width 5 beginning at position 
15, and y is to be printed in a field of width 10 also starting at position 15 with 2 places to the 


right of the decimal point. Furthermore, suppose that the variable names аге to appear in the пі 
named BOLDFONT and the values in font SMALLFONT. The program in ordinary Lisp that would 


accomplish these effects is too complicated to include here. With printout, one could write: 


| (PRINTOUT NIL .FONT BOLDFONT "X s" 15 .FONT SMALLFONT .I5 X T 
.FONT BOLDFONT "Y s" 15 .FONT SMALLFONT | 
.F10.2 Y T .FONT BOLDFONT) 


Тһе . FONT commands print on the file the font-changing instructions appropriate for a multi-font | 


output device (see Section 14). Тһе . 15 command sets up a FIX format for a call to the function 
printnum (see Section 14 ) to print X in the desired format. The .F10.2 specifies a FLOAT 
format for printnum | 
THE PRINTOUT FORM 


There are two parts to the expression that is the Lisp translation of a printout form. Тһе first part 


sets up a context in which printing is to be done in the case that a non-NIL file parameter is 


specified. In this case, the previous primary output file is remembered and the specified file is 
made primary during the execution of any Subsequent printing. When the printout form is 
completed, the сапісг primary file is restored.12* The second part of a printout translation contains 


122 i.e. if a non-NIL file parameter is specified, the printout must effectively be embedded іп a resetform (see Section 5). 


For this reason, if the user is going to be performing several calls to printout specifying the same, non-NIL file, it 
will be more efficient to embed them all іп a single resetform which changes the primary output file, and then 
specify file=NIL in the printout expressions themselves, 
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the Lisp expressions which actually carry out the list of printout commands. Notice that the 
printout commands are strung together, one after the other without punctuation, as cddr of the 
printout form. Some commands occupy a single position in this list, but many commands expect 
to find arguments following the command name in the list. 


The printout commands fall into several logical groups: one set deals with horizontal and vertical 
spacing, another group provides controls for certain formatting capabilities (font changes and 
subscripting), while a third set is concerned with various ways of actually printing items. Finally, 
there is a command that permits escaping to a simple Lisp evaluation in the middle of a printout 
form. | | | | 


HORIZONTAL SPACING COMMANDS 


The Bornzontal spacing commands provide convenient ways of calling tab and spaces. In the 
following descriptions, n stands for a literal positive integer. | | 


n used for absolute spacing. It results in a tab to position n (literally, - 


a (TAB n)). If the line is currently at position n n or beyond, the file 
-will be positioned at n on the next line. 


. TAB pos specifies tab to position (the value of) pos. This is one of several 
| commands whose effect could be achieved by simply escaping to 
Lisp, and executing the corresponding form. It is provided as a 
separate command so that the printout form is more concise and is 
prettyprinted more compactly. Note that . TAB n and n, NEIN n is 
an integer, are equivalent. | 


. TABO pos like . TAB except might result in zero врасев,123 


-n Negative integers indicate relative (as opposed to absolute) spacing. 
Translates as (SPACES |n]). | 


pe Provide a short-hand way of specifying 1, 2 or 3 spaces, i.e., these 
commands are equivalent to -1, -2, and -3, respectively. 


. SP distance Translates as (SPACES distance). Note that . SP n and -п, where n | 


is an integer, are equivalent. 


„КЕЗЕТ . Resets the current line by causing a carriage-rctum to be printed 


without a line-feed. Useful for overprinting, or for regaining . 


123 


i.e. the call to tab specifies minspaces=0. 
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control of a line on which characters have been piles in a 
variable рй font. | 


VERTICAL SPACING COMMANDS 


Vertical spacing is obtained by calling terpri or printing form-feeds. The relevant commands are: 


. SKIP lines 


„РАСЕ 


Translates as ( TERPRI ). This command is functionally equivalent 


to the integer command 0: they both move to position 0 
· (= column 1) of the next line. Note, to print the letter T, use the 


string "Т". 


| Equivalent to a sequence of lines (TERPRI)’s. Тһе .SKIP 


command allows for skipping large constant distances and for 
computing the distance to be skipped. 


Puts a form-feed (control-L) out on the file. Care is taken to make 


sure that Interlisp’s view of the current line position is correctly 
updated. 


SPECIAL FORMATTING CONTROLS 


There are a small number of commands for invoking some of the рано capabilities of 
multi-font output devices. The available commands are: 


.. FONT fontspec 


. SUP 


. SUB 


BASE 


Puts out a control sequence that causes a change to font fontspec | 
(the association between fontspec and a specific font must be | 
defined in the user's font profile, as described in Section 14). 
fontspec may be a font-name variable or an expression that 
evaluates to the value of a font-name variable. fontspec may also 
be a positive integer n, which is taken as an abbreviated reference 
to the font named FONTn (e.g. 1 = > ҒОМТ1). 


 Specifies superscripting. АП subsequent characters are printed 


above the base of the current line. Note that this is absolute, not 
relative: a . SUP following a .SUP is a no-op. | 


Specifies subscripting. Subsequent printing is below the base of the 
current line. As with superscripting, the effect is absolute. 


Movcs printing back to the base of the current line. Un-does a 
previous . SUP or .SUB; a no-op, if printing is currently at the 
base. | 
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PRINTING SPECIFICATIONS 


. The value of any expression in a printout form that is not recognized as a command itself or as а 
command argument is printed using prinl by default. For example, title strings can be printed by 
simply including the string as a separate printout command, and the values of variables and forms 
can be printed in much the same way. Note that a literal integer, say 51, cannot be printed by 
including it as a command, since it would be interpreted as a TAB; the desired effect can be 
obtained by using instead the string specification "51", or the form (QUOTE 51). 


For those instances when prinl is not appropriate, e.g. the user wants prin? instead, or he wants | 


list structures to be prettyprinted, the following commands are available: 


.Р2 thing Causes thing to be printed using prin2; translates as 


(PRIN2 thing). 


. PPV thing Causes thing to be prettyprinted at the current line position via 
printdef. The call to printdef specifies that thing is to be printed as 
a variable, not a function, so that nothing special is done for 
SELECTQ, PROG, etc. 


.РРЕ thing Prettyprints thing as part of a function definition. SELECTO, | 


PROG, etc. do receive special treatment. 


.PPVTL thing | Causes thing to be prettyprinted as a tail, that is, without the initial 
and final parentheses if it is a list. Useful for prettyprinting sub- 
lists of a list whose other elements are formatted with other 
commands. 


.PPFTL thing Prettyprints thing as a tail, and as part of a function definition. 


Paragraph format 


Interlisp’s prettyprint routines are designed to display the structure of S-expressions, but they аге 
not really suitable for formatting unstructured text. If a list is to be printed as a textual paragraph, · 
its internal structure is less important than controlling its left and right margins, and ће | 


indentation of its first line. The „РАКА and „РАКА? commands allow these parameters to be 
conveniently specified. 


. РАКА Imarg rmarg list Prints list in paragraph format, using prinl. Translates as 
(PRINTPARA imarg rmarg list) (see page 23.50) Example: 
(PRINTOUT T 10 .PARA 5 -5 LST) will print the elements of 
Ist as a paragraph with left margin at 5, right margin at 
(LINELENGTH)-S, and the first line indented to 10. 


„РАКА Imarg rmarg list Print as paragraph using prin2 instcad of prinl. ‘Translates as 
(PRINTPARA Imarg rmarg list T). 
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Right-flushing 


Two commands are provided for printing simple expressions flushed-right against a specified line 
position, using the function flushright. They take into account the current position, the number of 
characters in the print-name of the expression, and the position the expression is to be flush 
against, and then print the appropriate number of spaces to achieve the desired effect. Note that 
this might entail going to a new line before printing. Note also that right-flushing of expressions 
longer than a line (e.g. a large list) makes little sense, and the appearance of the output is not 
guaranteed. 


„ЕК pos expr | . Flush-right using prinl. The value of pos determines the position 
| | that the right end of expr will line up at. As with the horizontal 
. spacing commands, a negative position number means |розј 
columns from the current position, a positive number specifies the 
position absolutely. роѕ=0 specifies the right-margin, је. 5 
interpreted as (LINELENGTH). 


.FR2 pos expr | Flush-right using prin2 instead of prin]. 


Centering 


Commands for centering simple expressions between the current line position and another specified 
position are also available. As with right flushing, centering of large expressions is not guaranteed. 


. CENTER pos expr Centers expr between the current line position and the position 
| . Specified by the value of pos. А positive pos is an absolute position 
number, a negative pos specifies a position relative to the current 

position, and 0 indicates the right-margin. Uses prinl for printing. 


„СЕМТЕК pos expr Centers using prin2 instead of prinl. 


Numbering 


The following commands provide FORTRAN-like formatting capabilities for integer and 
floating-point numbers. Each command specifies а printing format and a number to be printed. 
The format specification translates into a format-list for the function printnum, which is ЕП 
іп Section 14. 


. Iformat number Specifies integer printing. Translates as a call to the function 
| printnum with a FIX format-list constructed from format. The 
atomic format is broken apart at internal pcriods to form the 

format-list. For схатре, .15.-8.T yields Ше  format-list 

(FIX 5 -8 Т), and the command scquence (... .15.-8.T 

FOO ...) will translate as (PRINTNUM '(FIX 5 -8 Т) FOO). 

It will cause the value of foo to be printed with radix -8 right- 

flushed in a По of width 5, with 05 used for padding on the left. 
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Internal NIL’s may be omitted, e.g. the commands .І5..Т апа 
. I5. NIL.T are equivalent. | 


. Fformat number Specifies floating-number printing. Like the format command, 
а except translates with а FLOAT format-list. | 


.N format number | Тһе .I and .Ғ commands specify calls to printnum with quoted 
format specifications. The .N command translates as (PRINTNUM 
format number), i.c., it permits the format to be the value of some 
expression. Note that, unlike the .I and .F commands, format is 


a separate element in the command list, not part of an atom 


beginning with .N. 


ESCAPING TO LISP 


There are many reasons for taking control away from printout in the middle of a long printing 


expression. Common situations involve temporary changes to system printing parameters (e.g. 
linelength), conditional printing (e.g. print foo only if fie is T), or lower- level iterative printing 
within a higher-level print specification. 


# form the escape command. form is an arbitrary Lisp expression that will 
be evaluated within the context established by the printout form, 
ie. form can assume that the primary output ше has been set цр 
appropriately, 


USER-DEFINED COMMANDS 


The collection of commands and options outlined above is aimed at fulfilling all common printing 
needs. However, certain applications might have other, more specialized printing idioms, so a 


facility is provided whereby the user can define his own commands. То do this, he must make © 


entries on the global list printoutmacros to define how his new commands are to be translated. 
printoutmacros is an a-list whose elements are of the form (command-name translation-function). 
Whenever command-name appears in command position in the sequence of printout commands (as 
opposed to an argument position of another command), translation-function is applied to the tail of 
Ше command-list. After inspecting as much of the tail as necessary, the function must return a list 
whose car is the translation of the user-defined command and its arguments, and whose cdr is the 
list of commands still remaining to be translated in the normal way. 


For example, suppose the user wanted to define a command "?", which will cause its single 
argument to be printed with prinl only if it is not NIL. He must enter (? ?TRAN) on 
printoutmacros, and dcfine the function ?tran as follows: | 


(LAMBDA (COMS) 
(CONS (SUBST COMS:2 'ARG 
‘(PROG ((ТЕМР ARG)) 
(AND TEMP (PRIN1 TEMP)))) 
COMS: :2)) 


23.49 


pede ts + + + + + + run 


+ + + + 


+ + + + + + + + + + + + + + + + + + + 


+++ 


++ + + ++ + + + + ++ ++ ++ 


+ 


Section 23: Clisp апа Dwimify 


Note that гап does not do any printing itself; it returns а form which, when evaluated in the 
proper context, will perform the desired action. This form should direct all printing to the primary 
output file. | 


SPECIAL PRINTING FUNCTIONS 


The paragraph printing commands are translated into calls on the function printpara, which may 
m be called directly: 


— тәнен rmarg; list:p2flg: parentie: file] 
Prints. list on file in line-filled aranh format with its first 
element b beginning at the current line position and ending at or 
before rmarg, and with subsequent lines appearing between Imarg 
and rmarg. If p2flg is non-NIL, prints elements using prin2, 
otherwise prinl. If parenflg is non-NIL, then parentheses will be 
printed around the elements of list. 


If Imarg is zero or positive, it is interpreted as an absolute column 
position. If it is negative, then the left margin will be at 
lImarg|--(POSITION) ІҒІтагр- NIL, the left margin will be at 
(POSITION), and the paragraph will appear in block format. . 


If rmarg is positive, it also is an absolute column position (which 
may be greater than the current (LINELENGTH)). Otherwise, it is 
interpreted as relative to (LINELENGTH), i.e., the right margin will- 
Бе at (LINELENGTH)--|rmarg. Example: (ТАВ 10) 
(РАТМТРАВА 5 -5 LST T) will prin2 the elements of Ist in a 
paragraph with the first line beginning at column 10, subsequent 
lines beginning at column 5, and all lines ending at or before 
(LINELENGTH)-5. 


. The current (LINELENGTH) is unaffected by printpara, and upon 
completion, file will be positioned immediately after the last 
character of the last item of list. printpara is a no-op if list is not a 
list. 


The right-flushing and centering commands translate as calls to the function flushright: 


flushright[pos; x;min;p2flg;centerflg: file] 
ТЕ centerflg = NIL, prints x right-flushed against position pos on file; 
otherwise, centers x between the current line position and pos. 
Makes sure that it spaces over at least min spaces before printing 
by doing a terpri if necessary; min=NIL is cquivalent to min 1. 
A positive pos indicates an absolute position, while a negative pos 
signifies the position which is |pos| to the right of the current line 


position. роз=0 is interpreted as (LINELENGTH), the right margin. 
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23.16 CLISP OPERATION 


.CLISP is a part of the basic Interlisp system. Without any special preparations, the user can 
include CLISP constructs in programs, or type them in directly for cvaluation in eval or apply 
format), then, when the "error" occurrs, and DWIM is called, it will дезігисііуеіу 74 transform the 
CLISP to the equivalent Interlisp expression and evaluate the Interlisp expression. User approval 
is not requested, and no message is printed.! | 


However, if а CLISP construct contains an error, ап appropriate diagnostic is generated, and the 
form is left unchanged. For example, if the user writes (LIST X+Y*), the error diagnostic 
MISSING OPERAND AT X+Y* IN (LIST X+Y*) would be generated. Similarly, if the user 
writes (LAST+EL X), CLISP knows that ((IPLUS LAST EL) X) is not a valid Interlisp. 
expression, so the error diagnostic MISSING OPERATOR IN (LAST+EL X) is generated. (For 
example, the user might have meant to say (LAST+EL*X).) Note that if LAST+EL were the 
name of a defined function, CLISP would never see this form. | 


Since the bad CLISP transformation might not be CLISP at all, for example, it might be a 
misspelling of a user function or variable, DWIM holds all CLISP error messages until after trying 
other corrections. If one of these succeeds, the CLISP message is discarded. Otherwise, if all fail, 
the message is printed (but no change is made)! 16 For example, suppose the user types 
(R/PLACA X Y). CLISP generates a diagnostic, since ((IQUOTIENT R PLACA) X Y) is 
obviously not right. However, since R/PLACA spelling corrects to /RPLACA, this diagnostic is 
never printed. | 


If a CLISP infix construct is well formed from a syntactic standpoint, but one or both of its 
operands are atomic and not bound,!2’ it is possible that either the operand is misspelled, e.g., the 
user wrote X+YY for X+Y, or that a CLISP transformation operation was not intended at all, but 
that the entire expression is a misspelling. For example, if the user has a variable named LAST- 
EL, and writes (LIST LAST-ELL). Therefore, CLISP computes, but does not actually perform, 
the indicated infix transformation. DWIM then continues, and if it is able to make another 
correction, does so, and ignores the CLISP interpretation. For example, with LAST-ELL, the 
transformation LAST-ELL -> LAST-EL would be found. 


If no other transformation is found, and DWIM is about to interpret a construct as CLISP for 
which one of the operands is not bound, DWIM will ask the user whether CLISP was intended, in 
this case by printing LAST-ELL TREAT AS CLISP 2128 


124 CLISP transformations, like all DWIM corrections, are undoable. 

125 This entire discussion also applies to CLISP transformation initiated by calls to DWIM from dwimify. 

126 Except that CLISP error messages are not printed on type-in. For example, typing X+*Y will just produce a U.B.A. 
X+*Y message. 

127 For the purpose of dwimifying, "not bound" means no top level value, not on list of bound variables built up by 
dwimify during its analysis of the expression, and not on nofixvarslst, i.e., not previously seen. 

128 


If more than one infix opcrator was involved in the CLISP construct, e.g., Х+Ү+2, or the operation was ап 
assignment to a variable already noticed, or treatasclispflg is T (initially NIL), the user will simply be informed of the - 
correction, e.g., X*Y*Z TREATED AS CLISP. Otherwise, even if DWIM was enabled in TRUSTING mode, the user 
will be askcd to approve the correction. 
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The same sort of procedure is followed with 8 and 9 errors. For example, suppose the user writes - 


FOO8*X where РОО8 is not bound. The CLISP transformation is noted, and DWIM proceeds. It 
next asks the user to approve FOO8*X -> FOO ( *X. (For example, this would make sense if 


the user has (or plans to define) a function named *X.) If he refuses, the user is asked whether 


Ғ008%Х is to be treated as CLISP. Similarly, if FOO8 were the name of a variable, and the user 


writes FOOO8*X, he will first be asked to approve Ғ0008%Х -> FOOO ( ХХ, 129 and if he 
. refuses, then be offered the FOOO8 -> Ғ008 correction. 


CLISP also contains provision for correcting misspellings of infix operators (other than single 
characters), IF words, and is. operators. This is implemented in such a way that the user who 
does not misspell them is not penalized. For example, if the user writes 
IF М=0 THEN 1 ELSSE N*(FACT N-1) CLISP does not operate by checking each word to see 
if it is a misspelling of IF, THEN, ELSE, or ELSEIF, since this would seriously degrade 
CLISP’s performance on ай IF statements. Instead, CLISP assumes that all of the IF words are 
spelled correctly, and transforms the | expression to 
(COND ((ZEROP N) 1 ELSSE N*(FACT N-1))). Later, after DWIM cannot find any other 
interpretation for ELSSE, and using the fact that this atom originally appeared in an IF statement, 


РУМ attempts spelling correction, using (IF THEN ELSE ELSEIF) for a spelling list. When 


this is successful, DWIM "fails" all the way back to the original IF statement, changes ELSSE to 


ELSE, and starts over. Misspellings of AND, OR, LT, GT, etc. are handled similarly. 


CLISP also contains many Do-What-I-Mean features besides spelling corrections. For example, the 
form (LIST +Х Y) would generate a MISSING OPERATOR error. However, (LIST -X Y) 
makes sense, if the minus is unary, so DWIM offers this interpretation to the user. Another 
common error, especially for new users, is to write (LIST X*FOO(Y)) or (LIST X*FOO Y), 
where FOO is the name of a function, instead of (LIST X*(FOO Y)). Therefore, whenever an 


operand that is not bound is also the name of a function (or corrects to one), the above 


interpretations are offered. 


23.17 CLISP INTERACTION WITH USER 


 Syntactically and semantically well formed CLISP transformations are always performed without 
informing the user. Other CLISP transformations described in the previous section, e.g., 


misspellings of operands, infix operators, parentheses errors, unary minus - binary minus errors, all 


follow the same protocol as other DWIM transformations (Section 17). That is, if DWIM has been 


enabled in TRUSTING mode, or the transformation is in an expression typed in by the user for 
immediate execution, user approval is not requested, but the user is informed. However, if the 
transformation involves a user program, and DWIM was enabled in CAUTIOUS mode, the user will 
be asked to approve. If he says NO, the transformation is not performed. Thus, in the previous 
section, phrases such as "one of these (transformations) succeeds" and "the transformation 
LAST-ELL -> LAST-EL would be found" etc., all mean if the user is in CAUTIOUS mode and 
the error is in a program, the corresponding transformation will be performed only if the user 


approves (or defaults by not responding). If the user says NO, the procedure followed is the same 


as though the transformation had not been found. For example, if А В appears in the function 
ЕОО, and B is not bound (and no other transformations are found) the user would be asked 


129 The 8-9 transformation is tried before spelling correction since it is empirically more likely that an unbound atom or 


undefined function containing an 8 or a 9 is a parenthesis error, rather than a spelling error. 


130 However, in certain situations, DWIM will ask for approval even if DWIM is enabled in TRUSTING mode. For 
cxample, the user will always be asked to approve a spelling correction that might also be interpreted as a CLISP 
transformation, as in LAST-ELL -> LAST-EL. 
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ТЕ the user approved, A*B would be transformed to (ITIMES А В), which would then cause а. 
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A*B [IN FOO] TREAT AS CLISP 7 131 


U.B.A. B error in the event that the program was being run (remember the entire discussion also 
applies to DWIMIF Ying). If the user said МО, АХВ would be left апопе.132 


23.18 CLISP INTERNAL CONVENTIONS 


Note: the reader can skip this section and proceed to "Function and Variables" (page 23.56), 
unless he wants to add new operators, or modify the action of емиш ones (other than by making 
declarations). 


CLISP is almost entirely table driven by property lists for the corresponding infix or prefix 
operators. Thus it is relatively easy to add new infix or prefix operators or change old ones, simply 
by adding or changing selected property values.¥ 


CLISPTYPE 


131 


132 


133 


134 


The property value of the property CLISPTYPE is the precedence 
number of the орегаќог: 134 higher values have higher precedence, 
ie. are tighter. Note that the actual value is unimportant, only the 
value relative to other operators. For example, CLISPTYPE for :, 
1, and * are 14, 6, and 4 respectively. Operators with the same 
precedence group left to right, e.g., / also has precedence 4, so 
A/B*C is (А/В) *С. 


An operator can have a different left and right precedence by 
making the value of CLISPTYPE be a dotted pair of two numbers, 
eg, CLISPTYPE of + is (8.-12). In this case, car is the left 
precedence, and cdr the right, i.e., car is used when comparing with 
operators on the left, and cdr with operators on the right. For 
example, А*ВєС+0 is parsed as А“ (В« (С+0)) because the left 


precedence of + 15 8, which is higher than that of *, which is 4. 


The right precedence of « is -12, which is lower than that of +, 
which is 2. 


Clisp bracket operators are defined by having the value of the 
CLISPTYPE property be the atom BRACKET for both left and right 
brackets, ер. for both < and >. See discussion of 
CLISPBRACKET below. 


The waiting time on such interactions is three times as long as for simple corrections, i.e., 3*dwimwait. 


If the value of clisphelpflg = 


NIL (initally T), the user will not be asked to approve any clisp transformation. Instead, 


in those situations where approval would be required, the effect is the same as though the user had been asked and 


said No. 


There is some built in information for handling minus, :, ', and ~, i.e., the user could not himself add such "special" · 


operators, although he can disable or redefine them. 


Unless otherwise specified, the property is stored on the property list of the operator, 
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If the CLISPTYPE property for any operator is removed, the 
corresponding CLISP transformation is disabled, as well as the 
inverse CLISPIFY transformation. 


The value of property UNARYOP must be T for unary operators or 
brackets. The operand is always on the right, i.e., unary operators 
or brackets are always prefix operators. | 


The value of property BROADSCOPE is T if the operator has lower 
precedence than Interlisp forms, e.g., LT, EQUAL, AND, etc. For 
example, (FOO X AND Y) parses as ((FOO X) AND Y). If the 
BROADSCOPE property were removed from the property list of 
AND, (FOO X AND Y) would parse as (FOO (X AND У)). 


The value of the property LISPFN is the name of the function to 
which the infix operator translates. For example, the value of 

LISPFN for t is EXPT, for ' QUOTE, etc. If the value of the · 
property LISPFN is NIL, the infix operator itself is also the — 
function e.g., AND, OR, EQUAL. | 


If FOO has a SETFN property ЕТЕ, then (FOO --)«X translates to 
(ЕТЕ -- X). For example, if the user makes ELT be an infix - 
operator, e.g. #, by putting appropriate CLISPTYPE and LISPFN 
properties on the property list of # then he can also make # 
followed by * translate to SETA, e.g., ХИМеУ to (SETA X N Y), 
by putting SETA on the property list of ELT under the property 
SETFN. Putting (ELT) (ie, list[ELT])) on the property list of 


ЗЕТА under property SETFN will enable SETA forms to CLISPIFY 
back to ELT's. 


The value of this property is the CLISP infix to be used in 
CLISPIFYing. This property is stored on the property list of the 
corresponding Interlisp function, e.g, the value of property 
CLISPINFIX for EXPT is т, for QUOTE is ' etc. 


appears on property list of clisp operators which can appear as car 
of a form, such as FETCH, REPLACE, ТЕ, iterative statement 
operators, etc. Value of property is of the form (keyword . name), 


where name is the lowercase version of the operator, and keyword 


is its type, e.g. FORWORD, IFWORD, RECORDWORD, etc. keyword 
can also be the name of a function; in which case when the atom 
appears as car of a form, thc function is applied to the form and 
the result taken as the correct form. 


In this case, the function should either physically change the form, or call clisptran to store the translation. 
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Global declarations operate by changing the corresponding LISPFN and CLISPINFIX properties. 


| clispchars 


clispcharray 


clispinfixsplst 


is a list of single character operators that еп appear іп Ше interior 


of an atom. Currently these аге: +, -, * /, t, ~," =, е, 5 €, 
апа >. AE | 


iS a. bit. table of the characters on clispchars used for calls to strposl 
(see Section 10). clispcharray is initialized by performing- 
(SETQ CLISPCHARRAY (MAKEBITTABLE CLISPCHARS) ). 


is a list of infix operators used for spelling correction. = 


As an | example, suppose the user wants to шке | бе ап infix нер operator meaning OR. He 


performs: 


«(РОТ (QUOTE |) (QUOTE идеи 
(СЕТР (QUOTE. ОВ) (QUOTE анық 


-PUT(| LISPFN OR) 


-PUT(| BROADSCOPE T) 
<РОТ (ОВ CLISPINFIX |) 
«5 ЕТО (С. 15РСНАН5 (CONS (QUOTE |) CLISPCHARS)) 
-SETQ(CLISPCHARRAY (MAKEBITTABLE CLISPCHARS)) 


CLISPBRACKE 


T 


Used for defining CLISP bracket operators. This property must be 
on the property list of both the left and right brackets, and also on 
the property list of any of the functions that expressions involving 
the brackets translate to (to enable clispifying). For the latter, the 
property value is simply the left bracket, e.g. <. For the brackets 


themselves, car of the property value is the left bracket, cadr the - 


right bracket, and cddr a list in property list format. The following 
properties are recognized: 


DWIMIFY function to be called to dwimify the construct: If the 
| bracket is a unary operator, the function will be 
applied to the list consisting of the (dwimified) 

segment between the matching brackets. 


If the bracket is not a unary operator, the function will 
be applied to the (dwimified) expression to the left of 
the bracket and the (dwimified) segment between the 
brackets. (See example below.) | 
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CLISPIFY (optional) function to be called when clispifying. 36 


SEPA RATOR (optional) character to be split from any atoms but 
. otherwise unprocessed, eg. for < and >, the 
` separator is ! 


For example, to define { | as a bracket which translates to elt in the case of a пра: expression, 
and multi- elt for more шап опе: 


“PUT ({ CLISPTYPE BRACKET) 
-PUT() CLISPTYPE BRACKET): | | 
-PUT(( CLISPBRACKET (( ) SEPARATOR , DWIMIFY FOO] 
еРОТ() CLISPBRACKET (( ) SEPARATOR , DWIMIFY FOO] 
-DEFINEQ[(FOO (A LST) - | 
(IF (MEMB ', LST) 
THEN <'MULTI-ELT A (FOR X IN LST COLLECT X WHEN X~=",)> 
ELSE <'ELT A! LST>] | 
–(МСОМС CLISPCHARS '(( } ,)) 
«(5ЕТ0 CLISPCHARRAY (MAKEBITTABLE тарымен 


Then, X: 1(N-1) will dwimify to (ELT (CAR X) (5081 ТЕ 
апа Z{N,M} will dwimify to (MULTI-ELT 7 М М) 


To enable clispifying, 


©PUT(ELT CLISPBRACKET () 
-PUT(MULTI-ELT CLISPBRACKET () 


Then, (MULTI-ELT (САРА A) (IQUOTIENT (5981 N) 2)) I) will clispify to 
| A:2((N-1)/2,I). 


23.19 CLISP FUNCTIONS AND VARIABLES. 


clispflg 


АҒ set to NIL, disables all CLISP infix or prefix transformations 


(but does not affect IF/THEN/ELSE statements, or iterative 
statements). 


If clispflg- TYPE-IN, CLISP transformations are performed only 
on expressions that are typed in for evaluation, i.e. not on user 


| programs. 


If clispflgz T, CLISP transformations are performed on all 


expressions. 


If the CLISPIFY property is not present, clispifying will consist of, for unary brackets, clispifying cdr of the form, 


inserüng the separator if any between each element, and surrounding the result with the brackets. For brackets that 
are not unary operators, cadr of {һе form is clispified and placed to the left of the brackets, and cddr of the form 
treated as above, 
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clisparray 


clisptran[x;tran] 
nofixfnslst 


nofixvarslst 


nospellflg 


clisphelpfig 


dwimify[x;quietflg;1] 


137 


138 
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The initial value for clispflg is T. clispifying anything will cause 
clispflg to be set to T. 


hash array used for storing translations. clisparray is checked by 
faulteval and faultapply on erroneous forms before calling DWIM, 
and by the compiler. 


gives x the translation tran. If clisparray is not NIL, uses hashing 
scheme, otherwise uses CLISP% scheme. See page 23.22-24.137 


list of functions that dwimify will not try to correct. See page 


23.41. 
list of variables that dwimify will not try to correct. See page 23.41. 


If позрећ Тр is T, dwimify will not perform any spelling corrections. 
The initial value of nospellflg is NIL. nospellflg is reset to T when 
compiling functions whose definitions are obtained from a file, as 
opposed to being in core. 


if NIL, dwimify will not ask the user for approval of any clisp 
transformations. Instead, in those situations where approval would 


be required, the effect is the same as though the user had been - 


asked and said No. 


dwimifies x, i.e., performs all corrections and transformations that 
would be performed if x were run, and prints the result unless 
quietflg = T. If x is an atom and 1 is NIL, x is treated as the name 
of a function, and its entire definition is dwimified. | 


Otherwise, if x is а list or 1 is not NIL, x is the expression to be 
dwimified. If 1 15 not NIL, it is the edit push-down list leading to 
x, and is used for determining context, i.e., what bound variables 
would be in effect when x was evaluated, whether x is a form or 
sequence of forms, е.р., a cond clause; etc, 138 


clisptran is called for all clisp translations, via a non-linked, external function call, ќе. it can be advised. 


If x is an iterative statement and 1 is NIL, dwimify will also print the translation, ie., what is stored in the hash 
array. 
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dwimifycompflg 


dwimcheck # argsflg 
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nlambda, nospread. Dwimifies each function on fns. If fns is a list 
of only one element, car[fns] is evaluated. If its value is a list, this 
list is used, e.g. dwimifyfns[FOOFNS]. If car[fns] is atomic, and its 
value is not a list, and car[fns] is the name of a known file, 
dwimifyfns wil ^ operate on filefnslst{car[fns]], eg. 
dwimifyfns[FOO. LS Р] will dwimify every function in the file 
FOO.LSP. | 


Every 30 seconds, dwimifyfns prints the name of the function it is 
processing, a la prettyprint. 


Value is a list of the functions dwimified. 


if T, dwimify is called before compiling an expression. See page 
23.42. 


if Т, causes dwimify to check for too many arguments іп а form. 


if T, causes dwimify to check whether a prog label contains a clisp 
character. 


if T (initially NIL), suppresses all dwimify error messages. 


puts into effect the declarations in declst. clispdec performs 
spelling corrections on words not recognized as declarations. 


clispdec is undoable. 


clispifies x. If x is an atom and 1 is NIL, x is treated as the name | 
of a function, and its definition (or EXPR property) is clispified. 
After clispify has finished, x is redefined (using /PUTD) with its 
new CLISP definition. The value of clispify is x. If x is atomic 
and not the name of a function, spelling correction is attempted. If 
this fails, an error is generated. 


If x is a list, or 1 is not NIL, x itself is the expression to be 
clispified. If 1 is not NIL, it is the edit push-down list leading to x 
and is used to determine context as with dwimify, as well as to 
obtain the local declarations, if any. The value of clispify is the 
clispificd version of x. 


See earlier section on CLISPIFY for more details. 
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clispifyfns[fns] nlambda, nospread. Like dwimifyfns except calls clispify instead of 
dwimify. 
cldisable[op] disables op, e.g., cldisable[-] makes - be just another character.139 


cldisable can be used on all CLISP operators, e.g., infix operators, 
prefix operators, iterative statement operators, etc. cldisable is 
undoable. 


clispiftranflg affects handling of translations of ТЕ | ТНЕМ | ELSE statements. If T, 
the translations are stored elsewhere, and the (modified) CLISP 
retained. If NIL, the corresponding COND expression, replaces the 
CLISP. clispiftranflg is initially NIL. See page 23.22. 


clispretranflg If T, informs dwimify to (re)translate all expressions which have 
remote translations, either in hash array or using CLISP%. Initially | 
NIL. 


cl:flg affects clispifys handling of forms beginning with car, cdr, 
cddddr, as well as pattern match and record expressions. See page 
23.39. 


clremparsflg affects clispify’s removal of parentheses from " small" forms. See 
page 23.39. | 


clispifypackflg if T, informs clispify to pack operator and atomic operands into 
single atoms; if NIL, no packing is done. See page 23.39. 


clispifyenglshflg if T, informs clispify to convert LISP expressions to english phrases- 
when possible. See page 23.21. 


clispifyprettyflg if non-NIL, causes prettyprint to CLISPIFY selected function 
definitions before printing them according to the following 


interpretations of clispifyprettyflg:1^0 


139 Simply removing a character operator from clispchars will prevent it from being treated as a clisp operator when it 


appears as part of an atom, but it will continue to be an operator when it appears as a separate atom, e.g. 
(FOO + X) vs ЕОО+Х. 


140 


Another way to inform prettyprint to clispify functions is for the function to have a CLISP declaration containing the 
word CLISPIFY. 
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funnyatomlst 
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. ALL all functions 
T,EXPRS functions currently defined as exprs 
CHANGES functions marked as having been changed 
a list a member of that list 


clispifyprettyflg is (temporarily) reset to T when makefile is called 
with the option CLISPIFY, and reset to CHANGES when the file 
being dumped has the property FILETYPE value CLISP. | 
clispifyprettyflg is initially М11..141 


if T, causes clispifyuserfn to be called on each form (list) not 
otherwise recognized by clispify. If a non-NIL value is returned, it 
is treated as the clispified form. 


If T, causes prettyprint to print translations instead of CLISP 
expressions. This is useful for creating a file for compilation, or for 
exporting {о a LISP system that does not have CLISP. 
prettytranflg is (temporarily) reset to T when makefile is called with 
the option NOCLISP. If prettytranflg is CLISPZ , both the CLISP 
and translations are printed in appropriate form. For more details, 
see page 23.23. prettytranflg is initially NIL. 


is both a function and an edit macro for prettyprinting translations. 
It performs a PP after first resetting prettytranflg to T, thereby 
causing any translations to be printed instead of the corresponding 
CLISP. 


edit macro that obtains the translation of the correct expression, if 
any, from clisparray, and calls edite on it. 


list of identifiers containing CLISP operators. Used by clispify to 


avoid accidentally constructing a user identifier, eg., 
(ITIMES A B) should not become A*B if A*B is the name of a 
PROG variable. See page 23.39. 


edit macro. Replaces current expression with CLISPIFYed current 
expression. Current expression can be an clement or tail. 


If clispifyprettyflg is non-NIL, and the only transformation performed by DWIM are well formed CLISP 


transformations, i.e., no spelling corrections, the function will not be marked as changed, since it would only have to 
be re-clispified and re-prettyprinted when the file was written out. | 
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edit macro. DWIMIFYs current expression, which can be an 
element (atom or list) or tail. 


Both CL and DW can be called when the current expression is either an element or a tail and will 


work properly. Both consult the declarations in the function being edited, if any, and both аге | 


undoable. 


lowercase[flg] 


араық о = LOSS есе 


If flg=T, lowercase makes the necessary internal modifications so 
that clispify will use lower case versions of AND, OR, IF, THEN,. 


ELSE, ELSEIF, and all is. operators. This produces more 
readable output. Note that the user can always type in either upper 
or lower case (or a combination), regardless of the action of 
lowercase. | | 


If flg - NIL, clispify will use uppercase versions of AND, OR, et al. 


The value of lowercase is its previous "setting". Lowercase is 
undoable. The initial setting for lowercase is T. | 
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LISPUSERS PACKAGES 


This chapter contains packages which are of sufficient utility that they would otherwise be included 
as part of the Interlisp system, except for virtual address space limitations. In Interlisp- -10, these 
packages normally reside on either the directory <LISP> or <LISPUS ERS>. 


24.1 PATTERN MATCH COMPILER! 


The pattern match compiler provides within CLISP a fairly general pattern match facility. The 
purpose of this pattern match facility is to make more convenient the specifying of certain tests 
that would otherwise be clumsy to write (and not as intelligible), by allowing the user to give 
instead a pattern which the datum is supposed to match. Essentially, the user writes "Does the 


(expression) X look like (the pattern) P?" For example, X:(& "А -- 'B) asks whether the _ 


second clement of X is an A, and the last element a B. The implementation of the matching is 
perforned by computing (once) the equivalent Interlisp expression which will perform the 
indicated operation, and substituting this for the pattern, and not by invoking each time a general 
purpose capability such as that found in FLIP or PLANNER. For example, the translation of 
X:(& 'A -- 'B) | is: 
(AND (EQ (CADR X) (QUOTE A)) (EQ (CAR (LAST X)) (QUOTE B))). Thus the 
CLISP pattern match facility is really a Pattern Compiler, and the emphasis in its design and 
implementation has been more on the efficiency of object code than on generality and 
sophistication of its matching capabilities. Тһе goal was to provide a facility that could and would 
be used суеп where efficiency was paramount, e.g., in inner loops. As a result, the CLISP pattern 
match facility does not contain (yet) some of the more esoteric fcatures of other pattern match 
languages, such as repeated patterns, disjunctive and conjunctive patterns, recursion, etc. However, 
the user can be confident that what facilitics it does provide will result in шыр expressions 
comparable to those he would generate by hand? 


The syntax for pattern match expressions is form:pattern, where pattern is a list as described below. 


As with iterative statements, the translation of patterns, 1.е., the corresponding Interlisp expressions, 


1 The pattern match compiler was written бу Г. M. Masinter. It can be loaded from the file MATCH.COM, or, since the | 
entries have а FILEDEF property, (see Section 17) simply using a pattern match construct will cause the file to be 
loaded automatically. 

2 


Wherever possible, already existing Interlisp functions are used іп the translation, e.g.. the translation of ($ "А $) 
uses MEMB, ($ ("А 5) $) uses ASSOC, etc. 
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are stored in clisparray, a hash array, as described in Section 23.5.. The original expression, 
form:pattern, is replaced by an expression of the form (MATCH form WITH pattern). CLISP 
also recognizes expressions input in this form. 


_ If form appears more than once in the translation, and it is not either a variable, or an expression 

that is easy to (re)compute, such as (CAR Y), (CDDR 7), etc, a dummy variable will be 
generated and bound to the valuc of form so that form is not evaluated a multiple number of 
times. For example, Ше translation of (FOO X):($ "А $) is — simply 
(MEMB (QUOTE A) (FOO X)), while the translation of (FOO X):('A 'B --) is: 


[PROG ($$2) (RETURN 
(AND (EQ (CAR (SETQ $$2 (FOO X))) 
(QUOTE A)) 
(EQ (CADR $$2) (QUOTE B]. 


In the interests of efficiency, the pattern match compiler assumes that all lists end in NIL, іе 
there are no LISTP checks inserted in the translation to check tails. For example, the translation 
of X:('A & --) is (AND (EQ (CAR X) (QUOTE A)) (CDR X)), which will match 
with (A B) as well as (А. "E Similarly, the pattern match compiler does not insert LISTP 
checks on elements, e.g, Х:(("А --) --) „translates simply as (EQ (CAAR X) (QUOTE А)), 
and X:(($1 $1 =) --) ав (CDAR X) Note that the user сап explicitly insert LISTP 
checks himself by using @, as described on page 243, eg, X:(($1 $1 --)@LISTP --) 
translates as (СОК (LISTP (CAR X))). 


PATTERN ELEMENTS 


A pattern consists of a list of pattern elements. Each pattern element is said to match either an 
element of a data structure or a segment. (cf. the editor’s pattern matcher, "--" matches any 
arbitrary segment of a list, while & or a subpattern match only one element of a list.) Those 
patterns which may match a segment of a list are called segment patterns; those that match a single 
element are called element patterns. 


ELEMENT PATTERNS 


There are several types of element patterns, best given by their syntax: 


The insertion of LISTP checks for elements is controlled by the variable patlistpcheck. When patlistpcheck is T, 
LISTP checks are inserted, e.g., Х: (('А --) --) translates as: | 

| (EQ (CAR (115ТР (CAR (115ТР Х)))) (QUOTE А)) 

patlistpcheck is initially NIL. Its value can be changed within a рне function by using a local dcelaradion, as 
described in Section 23.10. 
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PATTERN J MEANING 

$1, or & | matches an arbitrary element of а list 

"expression matches only an element which is equal to the given expression e.g., "А,4 
"(А В). 

= form | matches only an element which is equal to the value of form, e.g., =X, 


=(REVERSE Y). 


= = form same as =, but uses an eq check instead of equal. 
atom treatment depends on setting of patvardefault. 


If patvardefault 15 ' or QUOTE, same as ‘atom. 
If patvardefault is = or EQUAL, same as =atom. 

If patvardefault is == ог EQ, same as = =atom. 
If patvardefault is ог лы same as atome&, 
patvardefault is initially ' 


Note: numbers and strings are always interpreted. as though patvardefaul t were — , regardless of its 
setting. Ед, memb, and assoc are used for comparisons involving small integers. 


| (pattern; ... pattern) n > 1 
matches a list which matches the given patterns, е.в., (& 8), (-- 'A). 


element-pattern@fn matches an element if the element-pattern matches it, and fn (name of a 
| function or а LAMBDA expression) applied to that element returns 
non-NIL, e.g., &GNUMBERP matches a number, ("А --)@FOO matches a 
list whose first element is A, and for which FOO applied to that list is 
non-NIL.® 


4 eq, memb, and assoc are automatically used in the translation when the quoted expression is atomic, otherwise equal, 
member, and sassoc. 

5 patvardefault can be changed within a particular function by using a local declaration, as described іп Section 23.10. 

6 


For "simple" tests, the function-object is applied before a match is attempted with Ше pattern, e.g., 
((-- 'A --)@LISTP --) translates as (AND (115ТР (CAR Х)) (МЕМВ (QUOTE A) (CAR Х))), not 
the other way around. fn may also be a form in terms of the variable @, e.g., «(ЕО @ 3) 45 ОИ + 
to =3, + 
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* matches any arbitrary element. If the entire match succeeds, the element 
which matched the * will be returned as the value of the match. 


Note: normally, the pattern match compiler constructs an expression whose value is guaranteed to 
be non-NIL if the match succeeds and NIL if it fails. However, if a * appears in the pattern, the 
expression generated will either return NIL if the match fails, ог whatever matched the * even 
though that may Бе МІ. For example, ХОСТА ==) translates | as 
(AND (EQ (CAR X) (QUOTE A)) (CADR X)). | | у 


~element-pattern matches an element if the element is not matched by ени райе, e.g., 
~'A, ~=X, ~(-- 'А нау. 
(*ANY* element-pattern element-pattern . .) matches if any of the 
contained patterns match. 


SEGMENT PATTERNS 


$, or -- matches any segment of a list (including one of zero length). 

The difference between $ and -- is in the type of search they generate. For example, 
Х:(% "А "В $) translates as (EQ (CADR (MEMB (QUOTE А) X)) (QUOTE B)), whereas 
X:(-- "А "В 5) translates аз: [SOME Х (FUNCTION (LAMBDA (552 551) 


(AND (EQ 552 (QUOTE A)) (EQ (CADR 551) (QUOTE B]. Thus, а paraphrase of 
($ "А "В $) would be "Is Ше element following Ше first А a B?", whereas a paraphrase of 
(-- "А "В $) would be "15 there any A immediately followed by a В?" Note that the pattern 
employing $ will result in a more efficient search than that employing --. However, 
($ "А "В $) will not match with (X Y Z AM N O A B С), but (-- "А "В $) will. 


Essentially, once a pattern following a $ matches, the $ never resumes searching, whereas -- 
produces a translation that will always continue searching until there is no possibility of success. 
However, if the pattern match compiler can deduce from the pattern that continuing a search after 
a particular failure cannot possibly succeed, then the translations for both -- and $ will be the 
same. For example, both X:($ "А 53 $) and (-- "А $3 --) translate as 
(CDDDR (MEMB (QUOTE A) Х)), because if there are not three elements following the first A, 
there certainly will not be three elements following subsequent A’s, so there is no reason to 
continue searching, even for --. Similarly, ($ "А $ "В $) and (- А -- В --) are equivalent. 


$2, $3, etc. matches a segment of the given length. Note that $1 is not a segment 
pattern. | 
felement-pattern matches any scpment which the given element pattern would match as a 


list. For example, if the value of FOO is (A B С) !=FOO will match the 
segment .. A В С... etc. Note that !* is permissible and means Value- 
of-match + $, ср. Х:($ "А |") translates |0 
(СОК (МЕМВ (ОЏОТЕ А) Х)). 5 Є 


Note: since ! appearing in front of the last pattern specifies a match with some (ail of the given 
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expression, it also makes sense in this case for a ! to appear in front of a pattern that can only 
match with an atom, ср. ($2 !'A) means match if cddr of the expression is the atom A. 


similarly, Х:($ ! 'A) translates to (EQ (CDR (LAST X)) (QUOTE A)). 


'atom treatment depends on setting of patvardefault. If patvardefault is 
| QUOTE, same as latom (see above discussion). If patvardefault is = ог. 
EQUAL, same as !=atom. If patvardcfault is == or EQ, same as 

!— —atom. If patvardefault is © or SETQ, same as atom € $. 


The atom "." is treated exactly like !.’ In addition, if a pattern ends in an 
atom, the "" is first changed to !, eg, ($1 . A) and ($1 1 A) are 
equivalent, even though the atom "." does not explicitly appear in the 
pattern. 


Segment-pattern@function-object 
matches a segment if the segment- байын matches it, and the function 
object applied to the corresponding segment (as a list) returns non-NIL, 
ср. (S$@CDDR 'D $) matches (A B C D E) but not (АВ О Е), 
since CDDR of (A В) is NIL. yo 


Note: an (Q pattern applied to a segment will require computing the corresponding structure 
(with Idiff) each time the predicate is applied (except when the Segment in question is a tail of the 
list being matched). 


ASSIGNMENTS 


Any pattern element may be preceded by a variable and a "е", meaning if the match succeeds (i.e., 
everything matches), the variable given is to be set to what matches that pattern element. For 
example, if X = (AB C D E), X:($2 Үе53) will set Y to (C D E). Assignments are not 
performed until the entire match has succeeded. Thus, assignments cannot be used to specify а 
search for an element found earlier in the match, e.g., X:(Ye$1 =Y --) will not match with 
(A A B C ...).? This type of match is achieved by using place-markers, described below. 


7 With one exception, namely '.' preceding an assignment does not have the special interpretation that ! has preceding 
an assignment (see page 24.6). For example, Х:('А . FOO-'B) translates as: 
(AND (EQ (CAR X) (QUOTE A)) (EQ (CDR X) (QUOTE B)) (SETQ FOO (CDR X))), but 
X:('A | ЕООс"В) translates as: 
(AND (EQ (CAR X) (QUOTE A)) 
Қ (NULL (CDDR X)) 
(EQ (CADR X) (QUOTE B)) 
(SETQ FOO (CDR X))). 
8 The translation of this pattern is: 
(COND ((AND (CDR X) (EQUAL (CADR X) Y)) 
(SETQ Ү (CAR X)) 
T)). 
The AND is because if Y is NIL, the pattern should match with (A NIL), but not with just (A). The T is because 
(CAR X) might be NIL. 
9 


unless, of course, the value of Y was A before the match started.. 
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If the variable is preceded by а !, the assignment is to the zail of the list as of that point in the 
pattern, i.c., that portion of the list matched by the remainder of the pattern. For example, if X is 
(AB CD E), X:($ IYe'C "0 $) sets Y to (C D E), i.e, cddr of X. In other words, when 
! precedes an assignment, it acts as a modifier to the є, апа has no effect whatsoever on the 
pattern itself, e.g, X:('A 'B) and Х:("А !FOO«'B) match identically, and in the latter case, 
FOO will be set to CDR of X. 


Note: *«pattern-clement and !* epattern-clement are acceptable, e.g., Х: (5 "А *e('B --) --) 
translates as: 


ТО (552) (RETURN 
(AND (EQ (CAADR (SETQ 552 (MEMB (QUOTE А) Х))) 
(QUOTE B)) 
(CADR $$2] 


PLACE-MARKERS 


Variables of the form Жа, n a number, are called place-markers, and are interpreted specially by 
the pattern match compiler. Place-markers are used in a pattern to mark or refer to a particular 
pattern element. Functionally, they are used like ordinary variables, 1.е., they can be assigned 
values, or used freely in forms appearing in the pattern, e.g, Х:(#1651 =(ADD1 #1)) will 
match the list (2 3). However, they are not really variables in the sense that they are not bound, 


nor can a function called from within the pattern expect to be able to obtain their values. For 
convenience, regardless of the setting of patvardefault, the first appearance of a defaulted 


place-marker is interpreted as though patvardefault were е. Thus the above pattern could have 
been written as X: (#1 -(ADD1 #1)). Subsequent appearances of a place-marker are interpreted 
as though  patvardefault were =. For example, X:(#1 #1 --) 15 equivalent to 
X: (#1651 =#1 --), and translates as (AND (CDR X) (EQUAL (CAR X) (CADR x) ).19 


REPLACEMENTS 

Any pattern element may be followed by а "е" and a form, meaning if the match succeeds, the 
part of the data that matched is to be replaced (e.g., with RPLACA ог RPLACD)H with the value of | 
<form >. For example, if X =(A B C D E), X:($ "С $1+Y $1) will replace the third 
element of X with the value of Y. As with assignments, replacements are not performed until after 
it is determined that the entire match will be successful. 


Replacements involving segments splice the corresponding structure into the list being matched, 
e.g, if X is (A B C DEF) and FOO is (1 2 3), after the pattern ("А Ф-ЕОО "0 $) is 
matched with X, X will be (A 12 3 D E F), and FOO will be eq to CDR of x, ie, 
(12 ЗОЕ Е). X 


Note that ($ FOO+FIE $) is ambiguous, since it is not clear whether FOO ог ЕТЕ is the pattern 
element, 1.е., whether ¢ specifies assignment or replacement. For example, if patvardefault is = 


10 Just (EQUAL (CAR X) (CADR X)) would incorrectly match with (NIL). 


H The user can indicate he wants /rplaca and 4 /mplacd used, or frplaca and frplacd, by means of йене The initial 


defi 1ult is for rplaca and грѓасд. 
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this pattern can be interpreted as ($ Ғ00е-ҒТЕ $), meaning search for the value of ЕТЕ, and if 
found set FOO to it, or ($ <ЕООЕЕТЕ $) meaning search for the value of FOO, and if found, 
store the value of ЕТЕ into the corresponding position. In such cases, the user should 
disambiguate by not using the patvardefault option, i.c., by specifying ' or =. 


RECONSTRUCTION 


The user can specify a value for a pattern match operation other than what is returned by the 
match by writing after the pattern => followed by another form, e.g, Х:(Ғ006% "А -- 
) => (REVERSE F00),'* which translates as: | 


[PROG (552) (RETURN 
(COND ((SETQ $$2 (MEMB (QUOTE A) X)) 
(SETQ FOO (LDIFF X $2)) 
(REVERSE FOO]. 


Place-markers in the pattern can be referred to from within form, e.g., the above could also have 
been written as X:(!#1 'A --)=>(REVERSE #1). If -> is used in place of =>, the 
expression being matched is also physically changed to the value of form. For example, 
Х: (#1 "А 142) -> (CONS #1 #2) would remove the second element from X, if it were equal 
to А. 


In general, forml:pattern- > form2 is translated so as to compute form2 if the match is successful, 
and then smash its value into the first node of forml. However, whenever possible, the translation 
does not actually require form2 to be computed in its entirety, but instead the pattern match 
compiler uses form2 as an indication of what should be done to forml. For example, 
Х: (#1 "А 142) -> (CONS #1 #2) translates as | 
(AND (EQ (CADR X) (QUOTE А)) (RPLACD X (СООН Х))). 


EXAMPLES 
Кере ТА ==) -- matches any arbitrary segment. "А matches only ап А, and the 
2nd -- again matches an arbitrary segment; thus this translates to | 
(MEMB (QUOTE A) X). 
Х:(-- "А) Again, -- matches an arbitrary segment; however, since there is no 
-- after the "А, A must be the last element of X. Thus this 
translates to: (EQ (CAR (LAST X)) (QUOTE А)). 
X:('A "В -- "С 53 --) CAR of X must be A, and CADR must be B, and there must be at 
least three elements after the first C, so the translation is: 
(AND (EQ (CAR X) (QUOTE A)) 
(EQ (CADR X) (QUOTE B)) 
(CDDDR (MEMB (QUOTE C) (CDDR X)))) 


12 Тһе original CLISP is replaced by an expression of the form (MATCH Ғогт1 WITH pattern => form2). 


CLISP also recognizes expressions input in this form. 
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X:(('A 'B) "С Ye$1 $) Since ("А 'B) docs not end in $ or --, (CDDAR X) must be NIL. 
COND . 
((AND (EQ (CAAR X) (QUOTE A)) 
(EQ (CADAR X) (QUOTE B)) 
(NULL (CDDAR X)) 
(EQ (CADR X) (QUOTE C)) 
(CDDR X)) 
(SETQ Y (CADDR X)) 
T) 


X: (#1 "А $ 'B 'C #1 $) #1 is implicitly assigned to the first element in the list. The $ 
searches for the first B following A. This B must be followed by a 
C, and the C by an expression equal to the first element. 


[PROG ($$2) (RETURN 
(AND (EQ (CADR X) (QUOTE A)) | 
(EQ [CADR (5ЕТ0 552 (МЕМВ (QUOTE В) (CDDR Х1 
(QUOTE C)) 
(CDDR $$2) 
(EQUAL (CADDR $$2) (CAR X] 


X: (#1 "А -- "В "С #1 $)Similar to the pattern above, except that -- specifies a search for 
any B followed by a C followed by the first clement, so the 
translation 15: 


[AND (EQ (САРА X) (QUOTE А)) 
(SOME (CDDR X) (FUNCTION (LAMBDA ($$2 $$1) 
(AND (EQ $$2 (QUOTE B)) 
(EQ (CADR $$1) (QUOTE C)) 
(CDDR $$1) 
(EQUAL (CADDR $$1) (CAR Х] 


This concludes the description of the pattern match compiler. 


24.2 EDITA? 


Edita is an editor for arrays. However, its most frequent application is in editing compiled 
functions (which are also arrays in Interlisp-10), and a great deal of effort in implementing edita, 
and most of 15 special features, are in this area. For cxample, сайа knows the format and 


13 edita was written by W. Тейсітап, and modified by D. C. Lewis. That portion of edita relating to compiled code 
may or may not bc available in implementation of Interlisp other than Interlisp-10. edita is contained on the Ше 
EDITA.COM, edita also has a FILEDEF property so that the user can спри call cdita and Ше file will be 
automatically loaded. 
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conventions of Interlisp-10 compiled code, and so, in addition to decoding instructions а la DDT ‚14 
саца can fill in the appropriate COREVALS, symbolic names for index registers, references to 
literals, linked function calls, etc. The following output shows a sequence of instructions in a 
compiled function first as they would be printed by DDT, and second by edita. 


466716/ PUSH 16,LISP&KNIL 3/ PUSH PP,KNIL 
466717/ PUSH 16,LISP&KNIL 4/ PUSH PP,KNIL 
466720/  HRRZ 1,-12(16) 5/  HRRZ 1,-10(PP) 
466721/ CAME 1,LISP&KNIL 6/ САМЕ 1,KNIL 
466722/ JRST 466724 | 7/ ЈАТ 9 
466723/  HRRZ 1,@467575 8/  HRRZ 1,@'BRKFILE 
466724/ PUSH 16,1 9/ PUSH РР,1 
466725/  LISP&IOFIL, ‚467576 10/ PBIND 'BRKZ 
466726/  -3,,-3  — 11/ -524291 
466727/ HRRZ 1,-14(16) 12/ HRRZ 1,-12(PP) 
466730/  CAMN 1,467601 13/ САММ 1,'OK 
466731/  JRST 466734 14/ JRST 17 
466732/ САМЕ 1,467602 15/ CAME 1,'STOP 
466733/  JRST 466740 16/ JRST 21 
466734/ PUSH 16,467603 17/ PUSH PP, 'BREAK1 
466735/ PUSH 16,467604 18/ PUSH PP,'(ERRORI) 
466736/  LISP&FILEN, , 467605 19/ CCALL 2,'RETEVAL 
466737/  JRST 467561 20/ JRST 422 
466740/ CAME 1,467606 21/ CAME 1,'60 

 466741/  JRST 466754 . 22/ JRST 33 
466742/  HRRZ 1,0-12(16) 23/ HRRZ 1,@-10(PP) 
466743/ PUSH 16,1 24/ PUSH РР,1 


Therefore, rather than presenting edita as an array editor with some extensions for editing compiled 
code, we prefer to consider it as a facility for editing compiled code, and point out that it can also 
be used for editing arbitrary arrays. | 


OVERVIEW 
To the user, edita looks very much like DDT with Interlisp-10 extensions. It is a function of one 
argument, the name of the function to be едцед 16 Individual registers or cells in the function may 


be examined by typing their address followed by a slash,! e.g. 
6/  HRRZ 1,-10(PP) 


14 DDT is one of the oldest debugging systems still around. For users unfamiliar with it, let us simply say that edita - 
was patterned after it because so many people are familiar with it. 

5 Note that edita prints the addresses of cells contained іп the function relative to the origin of the function. 

16 Аһ optional second argument can be a list of commands for edita. These are then executed exactly as though they 
had come from the teletype. 

17 


Undcrlined characters were typed by the user. edita uses its own read program, so that it is unnecessary to > type a 
space before the slash or to type a carriage return after the slash. 
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The slash is really a command to edita to open the indicated register. 18 Only one register at a time | 
can be open, and only open registers can be changed. ‘Yo change the contents of a register, the user 
first opens it, types the new contents, and then closes the register with a carriage- return? eg. 


7/ CAME 1,74 САММ 1, ‘ta 


If the user closes a register without specifying the new contents, the contents are left unchanged. 
. Similarly, if an error occurs or the user types control-E, the open register, if апу, is closed without 
being changed. | 


INPUT PROTOCOL 


Edita processes all inputs not recognized as commands in the same way. If the input is the name 
of an instruction (1.е., an atom with a numeric OPD property), the corresponding number is added 
to the input value being assembled, and а flag is set which specifies that the input context is that 
of an instruction. | 


The general form of a machine instruction is (opcode ac, (2 address (index)) as described in 
Section 18. Therefore, in instruction context, edita evaluates all atoms (if the atom has a COR EVAL 
property, the value of the COREVAL is used), and then if the atom corresponds to an ас,21 shifts it 
left 23 bits and adds it to the input value, otherwise adds it directly to the input value, but 
performs the arithmetic in the low 18 bits. Lists are interpreted as specifying index registers, and 
the value of car of the list (again COREVA Ls are permitted) is shifted left 18 bits. Examples: 


PUSH РР, KNIL 
HRRZ 1,-10(PP) 
CAME 1, 'GO 
JRST 33 ORG 23 


The user can also specify the address of a literal via the ' command, see page 24.13. For 
example, if the literal " UNBROKEN" is in cell 85672, HRRZ 1,"" UNBROKEN" 15 ae to 
HR RZ 1, 85672. — | | | 


When the input context is лог that of an instruction, i.e., по OPD has been seen, all inputs are - 


22 


| 18 edita also converts absolute addresses of cells within the function to relative address on input. Thus, if the definition 
of foo begins at 85660, typing 6/ is exactly the same as typing 85666/. | } 

19. Since carriage-return has а special meaning, edita indicates the balancing of parentheses by typing a space. 

20 The input value is initially 0. 

21 ie. if a "," has not been seen, and the value of the atom is less than 16. and Ше low 18 bits of the input value are 
all zero. | 
If the absolute value of the atom is greater than 10000000, full word arithmetic is used. For example, the indirect bit 
is handled by simply binding @ to 20000000Q. 

23 


edita cannot in general know whether an address field іп an instruction that is typed in is relative or absolute. 


Therefore, Ше user must add ORG, the origin of the function, to the address field himself. Note that edita would . 
print this instruction, JRST 53 ORG, as JRST 53. 
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evaluated (the value of an atom with a COREVAL property is the COREVAL.) Then numeric values 
are simply added to the previous input value; non-numeric values become the input value. 


The only exception to the entire procedure occurs when a register 15 open that is in the pointer 
region of the function, i.e., literal table. In this case, atomic inputs are not evaluated. For 
схатріе, the user can change the literal FOO to FIE by simply opening that register ана then 
typing FIE followed by carriage-return, e.g. 


"ЕО0/ ЕОО FIE? 


Note that this is equivalent to 'F00/ FOO (QUOTE FIE)? 


EDITA COMMANDS AND VARIABLES 


2 (carriage-return) | If a register is open and an input was typed, store the input in the 
register and close it. 


If a register is open and nothing was typed, close the register 
without changing it. 


If a register is not open and input was typed, type its value. 


ORG Has the value of the address of the first instruction in the function. 
i.e., loc of getd of the function. 


/ Opens the register specified by the low 18 bits of the quantity to 
the left of the /, and types its contents. If nothing has been typed, 
it uses the last thing typed by edita, e.g., 


35/ JRST 53 / САМЕ 1,'RETURN / RETURN 
If a register was open, / closes it without changing its contents. 


After a / command, edita returns to that state of no input having 
been typed. 


tab (control-I) | Same as carriage-return, followed by the address of the quantity to 
the lefi of the tab, e.g., 


35/ JRST 53 tab 


J 
53/ CAME 1, RETURN 


Note that if a register was open and input was typed, tab will change the open register before 
closing it, e.g., 


24 Presumably there is only one input in this case. 


25 If the register is in the unboxed region of the function, the unboxed value is stored in the register. 
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$Q (<esc>Q) 


LITS 


BOXED - 


$ (dollar) 


OK 
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35/ JRST 53  JRST 54 tab 
54/ JRST 70 2 
35/ JRST 54 


has the value of the address of the current (last) register examined. 


same as carriage-return followed by (ADD1 .)/ іе. closes any 
open register and opens the next register. 


same as carriage-return followed by (SUB1 .)/ 


has as its value the last quantity typed by edita e.g. 


5/ JRST 53 $0 12 


./ | JRST 54 


has as value the (relative) address of the first literal. 


same as LITS 


has as value the relative address of the last literal in the function. 


. Sets radix to -8 and types the quantity to the left of the — sign, 


ie. if anything has been typed, types the input value, otherwise, 


_ types $Q, e.g. 


35/ JRST 54 -2540002415410 


. JRST 54-2540000000660 


. Following =, radix is restored and edita returns to the no input 


state. 


leave edita 


return to "no input" state. ? is a "weak" control-E, i.e., it negates 
any input typed, but does not close any registers. па? 
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addressl, address2/ prints? the contents of registers addressl through address2. . is set 
| to address2 after the completion. 


'X corresponds to the ' in LAP. The next expression is rcad, and if it 
| is a small number, the appropriate offset is added to it. Otherwise, 
the literal table is searched for x, and the value of 'x is the 
(absolute) address of that cell. An error is generated if the a is 
not found, i.e., ' cannot be used to create literals. 


- ајот defines atom to an address 

(1) the value of $Q if a register is open, 

(2) the input if any input was typed, otherwise 
(3) е value of ".".27 | 
For example: 


5/ JRST 54 :Ғ0029 


: ТЕ) 
FIE/ JRST FOO.=35 


Кыа niente) 


Edita keeps its symbol tables on two free variables, usersyms and symlst. Usersyms is а list of 
elements of the form (name . value) and is used for encoding input, i.e., all variables on usersyms 
are bound to their corresponding values during evaluation of any expression inside edita. Symlst is 
a list of elements of the form (value . name) and is used for decoding addresses. Usersyms is 
initially NIL, while symlst is set to a list of all the corevals. Since the : command adds the 
appropriate information to both these two lists, new definitions will remain in effect even if the 
user exits from edita and then reenters it later. 


Note that the user can effectively define symbols without using the : command by appropriately 
binding usersyms and/or symlst before calling edita. Also, he can thus use different symbol tables 
for different applications. 


$W (<esc>W) search command. 


Searching consists of comparing the object of the search with the contents of each register, and. 
printing those that match, e.g., 


HRRZ Ө $W? 

8/ НЕК? 1,0 "ВЕКҒПЕ 
23/ HRRZ 1,0-10(РР) 
28/ HRRZ 1,@-12(PP) 


26 output gocs to file, initially set to Т. The user can also set file (while in edita) to the name of a disc file to redirect 
the output. (The user is responsible for opening and closing file.) Note that file only affects output for Ше address], 
address2/ command, 

27 


Only the low 18 bits are used and converted to a relative address whenever possible. 
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The $W command can be used to search either the unboxed portion of a function, 1.е., instructions, 
or the pointer region, i.e., literals, depending on whether or not the object of the scarch is a 
number. If any input was typed before the $W, it will be the object of the search, otherwise the 


next expression is read and used as the object.28 The user can specify a starting point for the 
search by typing an address followed by a "," before calling $W, e.g., 1, JRST $W. If no starting 


point is specified, the search will begin at 0 if the object is a number, otherwise at LITS, Ше 
address of the first literal. After the search is completed, "." is set to the address of the last 
register that matched. | 


If the search is opcrating іп the unboxed portion of the function, only those fields (1.е., instruction, 
ac, indirect, index, and address) of the object that contain one bits are compared. For example, 
HRRZ @ $W will find all instances of HRRZ indirect, regardless of ac, index, and address fields. 
Similarly, ‘PRINT $W will find all instructions that reference the literal PRINT.3l 


If the search is operating in the pointer region, a "match" is as defined in the editor. For example, 


$W (&) will find all registers that contain a list consisting of a single expression. 


ФС (Се5с?С) | like $W except only prints the first match, then prints the number 
| of matches when the search finishes. 
EDITING ARRAYS 


Edita is called to edit a function by giving it the name of the function. Edita can also be called to 
edit an array by giving it the array as its first argument," 32 in which case the following differences 


are to be noted: 


1. decoding - Тһе contents of registers in the unboxed region are boxed and printed as 
numbers, i.e., they are never interpreted as instructions, as when editing a function. 


2. addressing convention - Whereas 0 corresponds to the first instruction of a function, the 
first element of an array by convention is element number 1. | 


28 Note that inputs typed before the $W will have been processed according to the input protocol, i.e., evaluated; inputs 
typed after the ФМ will not. Therefore, the latter form is usually used to specify searching the literals, е.р., $W FOO is 
equivalent to (QUOTE FOO) $w. 

2 Thus the only way the user can search the pointer region for a number is to specify the starting point ма ",”. 

30 Alternately, the user can specify his own mask by sctting the variable mask (while in edita), to the appropriate bit 
pattern. 

31 Тһе user may need to establish instruction context for input without giving a specific instruction. For example, 
suppose the user wants to find all instructions with ac=1 and index=PP. In this case, the user can give & as a 
pscudo-instruction, e.g, type & 1, (РР). 

32 


the array itself, not a variable whose value is an array, e.g., (EDITA FOO), not EDITA(FOO). 
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3. input protocols - If a register is open, lists are evaluated, atoms are not evaluated 
(except for $Q which is always evaluated). If no register is open, all inputs are 
evaluated, and if the value is a number, it is added to the "input value". 


4. left half - If the left half of an element in the pointer region of ап array is not all 0’s or 
NIL, it is printed followed by a ;, e.g. | 
10/ (АВ); 


Similarly, if a register is closed, either its left half, де half, ог both halves can be | 
‘changed, depending on the presence or absence, and position of the ; e.g. | 


107 (АВ); Т | B;2 changes left. 
/ в; T NIL? x changes right 
Z B; NL A; Сә changes both 
КА А; С 


If ; is used in the unboxed portion of an array, an error will be generated. 


The $W command will look at both halves of elements in the pointer region, and match if either 
half matches. Note that $W A ; В is not allowed. 


This concludes the discussion of edita. 


24.3 PRINTING REENTRANT AND CIRCULAR LIST STRUCTURES - 


CIRCLPRINT?? 


Horribleprint (Section 14) is designed primarily for dumping circular or reentrant list structures (as 
well as other data structures for which read is not an inverse of print) so that they can be read 
back in by Interlisp. The circlprint package is designed for printing circular or reentrant structures 
so that the user can look at them and understand them. 


А reentrant list structure is one that contains more than one occurrence of the same (eq) structure. 
For example, tconc (Section 6) makes uscs of reentrant list structure so that it does not have to 
search for the end of the list each time it is called. Thus, if x is а list of 3 elements, (A B C), 
being constructed by tconc, the reentrant list structure used by tconc for this purpose is: 


33 CIRCLPRINT was written by P. C. Jackson. It is contained on the file CIRCLPRINT.COM. 


24.15. 


Section 24: Lispusers Packages 


FIGURE 24-1 


This structure would be printed by print as ((A B С) C). Note that print would produce the 
same output for the non-reentrant structure: 


FIGURE 24-2 


In other words, print does not indicate the fact that portions of the structure in Figure 24-1 are 
identical. Similarly, if print is applied to a circular list structure (a special type of reentrant 
structure) it will never terminate. 


For example, if print is called on the structure: 


FIGURE 24-5 


it will print an endless sequence of left parentheses, ånd if applied to: 
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FIGURE 24-4 


will print a left parenthesis followed by an endless sequence of A’s. 


The function circlprint described below produces output that will exactly describe the structure of 
any circular or reentrant list structure. This output may be in either single or double-line formats. 
Below are a few examples of the SAPICSSIOnS that circlprint would produce to describe the 


structures discussed above. 


expression in Figure 24-1: 


single-line: 
double-line: 


expression in Figure 24-3: 


single-line: 


double-line: 


expression in Figure 24-4: 


single-line: 
double-line: 


(A B *1* C) (1)) 
(A S ед) o 


(*1* (1)) 


(G1) 
1 


(*1* A . (1) 


(А . (1)) 
1 
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The more complex structure: 
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is printed as follows: 
single-line: x 
 double-line: 


FIGURE 24-5 


(ван (*1* (1) *3* (2) А *4*B . (3)) . (4). 
(ОЈ Аш и В. (37). (4)) | 


In both formats, the reentrant nodes in Ше list structure аге labeled by numbers. (A reentrant 
. node is one that has two or more pointers coming into it.) In the single-line format, the label is 
printed between asterisks at the beginning of the node (list or tail) that it identifies. In the 
double-line format, the label is printed below the beginning of the node it identifies. An 
occurrence of a reentrant node that has already been identified is indicated by printing its label in 


brackets. | 


circlprint[list;printflg; rlknt] 


circlmark[list;rlknt] 


Піргіл [list] 


prints an expression describing list. If printflg = NIL, double-line | 
format is used, otherwise single-line format. circlprint first calls 
circlmark[list;rlknt], and then calls cither Прпп [list] or rlprin2f[list], 
depending on the value of printflg (T or NIL, respectively). 
Finally, rlrestore[list] is called, which restores list to its unmarked 
state. Value 1s list. 


marks each reentrant node in list with a unique number, starting at 


rlknt - 1 (or 1, if rlknt is NIL). Value is (new) rlknt. 


Marking list physically alters it. However, the marking is 
performed undoably. In addition, list can always be restored by 
specifically calling rlrestore. 


prints an expression describing list in the singlc-linc format. Does 

not restore list to its uncirclmarked state. list must previously have 

been circlmarked or an error is generated. | 
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rlprin2flist] same as riprinl, except that the expression describing list is printed 
in the double-line format. 


rirestore[list] physically restores list to its original, unmarked state. 


Note that the user can mark апа print several structures which together share common 
substructures, e.g., several property lists, by making several calls to circlmark, followed by calls to 
rlprinl or гіргіп2, and finally to гігеѕібге. 


circlmaker[list] 222 list may contain labels and references following the convention used 

| by circlprint for printing reentrant structures in single linc format, 
eg, (*1* . (1)). circlmaker performs the necessary rplaca's 
and rplacd's to make list correspond to the indicated structure. 
Value is (altered) list. 


circlmakerl [list] . Does the work for circlmaker. Uses free variables labelst and reflst. 
labelst is a list of dotted pairs of labels and corresponding nodes. 
reflst is a list of nodes containing references to labels not yet seen. 
Circlmaker operates by initializing labelst and reflst to NIL, and 
then calling circlmakerl. It generates an error if reflst is not NIL 
when circlmakerl returns. The user can call circlmakerl directly to 
"connect up" several structures that share common substructures, 
e.g., several property lists. | 


РВІМТІ 34 


The printl package uses а different scheme than circlprint to present circular structures іп ап easily 
readable format. printl uses indentation a la prettyprint to make it easier for the user to see the 


nesting of list structure, and prints index numbers for the beginning and ends of expressions 50. 


that the user can find what is referred back to easily. The following example illustrates the use of 
printl: 


34 PRINTL was written by M. J. Kay. И is contained on the Пе PRINTL.COM. 


35 


Note that print! docs not provide an output format which can be read back in to reconstruct the original list 
structure; it is intended primarily as a debugging aid. 
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32¢(PRINTL (NCONC (SETQQ X (A B C D)) Х)) 


1: (ABCD. {1}) :1 
NIL | | 
33¢(PRINTL (LIST X (CDR X) (CDDR X) (CDDDR X] 
Ns ((ABCD. {2}) {3} {4} (57) | 2241 


34¢(PRINTL (LIST X (CONS 'Р (CDR X)) (CONS "0 (CDDR X)) 
(CONS 'R (CDDDR X] 


1: ((АВ СО . {2}) 2 
6: (Р. {3}) 6 
7: (0. {4}) 7 
8: (А. {5})) 1 
NIL 
35¢USE LIST FOR CONS 
1: ((АВ СО . {2}) :2 
6: (P (3)) :6 
8: (Q (4)) 8 


10: (R {5})) 
NIL | 


printl uses the following algorithm: Each list node that is printed (car or cdr) is assigned a number. 
The second and subsequent appearences of this list node are represented simply by printing the 


number corresponding to the node in | brackets. Every line on which the representation of a list 


begins shows the corresponding number of the first such list, ie. this number corresponds to the 
first open parenthesis on the line. Similarly, to the right of every line on which a list ends is. 
printed the number that corresponds to Ше /ast close parenthesis on the line. The numbers for 
those list nodes which do not correspond to the first open parentheses or the last close parentheses 
on a line can be obtained by simply counting from the last numbered parenthesis. For example, in 
the line | 


1: (A BC D . (2)) (3) (4) (5) ШЕ E 
2is (A B C D),3is (B C D),4 5 (C D), and 5 is (D). 


printl[item;depth;lmarg;rmarg; file] | 
prints ап item which is known to be, or suspected of being 
circular list structure, in the form described above. depth controls 
the depth of recursion in the car direction and defaults to the value 
of the varible printdcpth (initially 4). Elements of the structure at 
this depth are printed as 4--. 


Imarg is the left margin. If NIL, Imarg defaults to position[file]. rm 
is the position at which the righthand column of numbers will be 
printed. If NIL, rm defaults to (LINELENGTH) -5. 


Printing is to file, which is opened if necessary. 


PRNTL args lispxmacro that performs (PRINTL . args) provided car[args] is not 
| a number. If it is, or if агро == NIL, the item to be printed is taken 
to be the last суспі on the history list with a non-null value. Thus 
PRNTL 6 will print the last non-null value with depth =6. 
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INTRODUCTION 


transor is a LISP-to-LISP translator intended to help the user who has a program coded in one 


dialect of LISP and wishes to carry it over to another. The user loads transor along with a file of 
transformations. These transformations describe the differences between the two LISPs, expressed | 
іп terms of Interlisp editor commands needed to convert the old to new, i.e. to edit forms written · 
in the source dialect to make them suitable for the target dialect. transor then sweeps through the 
user’s program and applies the edit transformations, producing an object file for the target system. 
In addition, transor produces a file of translation notes, which catalogs the major changes made in 
the code as well as the forms that require further attention by the user. Operationally, therefore, 
transor is a facility for conducting massive edits, and may be used for any purpose which that may 
suggest, | 


Since the edit transformations are fundamental to this process, let us ben with a definition and 
some examples. A transformation is a list of edit commands associated with a literal atom, usually 
a function name. transor conducts a sweep through the user's code, until it finds a form whose car 


is a literal atom which has a transformation. The sweep then pauses to let the editor execute the | 


list of commands before going on. For example, suppose the order of arguments for the function 
tconc must be reversed for the target system. The transformation for tconc would then be: ( (SW 
2 3)). When the sweep encounters the form (TCONC X (ЕОО)), this transformation would be 
retrieved and executed, converting the expression to (TCONC (Ғ00) X). Then the sweep would 
locate the next form, in this case (FOO), and any transformations for foo would be теше, etc, 


Most instances of tconc would be successfully translated by this йсй. However, if there | 
were no second argument to tconc, e.g. the form to be translated was (TCONC X), the command. 
(SW 2 3) would cause an error, which transor would catch. The sweep would go on as before, 
but a note would appear in the translation listing stating that the transformation for this particular 
form failed to work. The user would then have to compare the form and the commands, to figure 
out what caused the problem. Опе might, however, anticipate this difficulty with a more 
sophisticated transformation: ((IF (ҰЯ 3) ((SW 2 3)) ((-2 NIL)))), which tests for a 
third element and does (SW 2 3) or (-2 NIL) as appropriate. It should be obvious that the 
translation process is no more sophisticated than the transformations used. 


This documentation is divided into two main parts. The first describes how to use transor 
assuming that the user already has a complete set of transformations. The second documents 
transorset, an interactive routine for building up such sets. transorsct contains commands for 
writing and editing transformations, saving one's work оп a file, testing transformations by 

translating sample forms, etc. | | 


Two transformations files presently exist for translating programs into  Interlisp. 


< LISP > SDS940.XFORMS is for old BBN LISP (SDS 940) programs, апа 
< LISP > LISP16.XFORMS is for Stanford Al LISP 1.6 programs. A set for LISP 1.5 is planned. 


36 TRANSOR was written by J. W. Goodwin. It is contained on the file TRANSOR . СОМ, 
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С USING TRANSOR 


The first and most exasperating problem in carrying a program from one implementation to 
another is simply to get it to read in. For example, SRI LISP uses / exactly as Interlisp uses %, 
ie. as an escape character. The function prescan exists to help with these problems: the user uses 
prescan to perform an initial scan to dispose of these difficulties, rather than attempting to transor 
the foreign sourcefiles directly. 


prescan copies a file, performing character-for-character substitutions. It is hand-coded and is 
much faster than either readc's or text-editors. | 


prescan[file;charlst] Makes a new version of file, performing substitutions according to 
charlst. Each element of charlst must be a dot-pair of two character 
codes, (OLD . NEW). 


For example, SRI files are prescan’ed with charlst = le 47) (47 . 37)), which exchanges slash 
(47) and percent-sign (37). 


The user should also make sure that the treatment of doublequotes by the source and target 
systems is similar. In Interlisp, an unmatched double-quote (unless protected by the escape 
character) will cause the rest of the file to read in as a string. | 


Finally, the lack of a STOP at Ше end of a file is harmless, since transor will suppress END OF 
FILE errors and exit normally. 


TRANSLATING 


transor is the top-level function of the translator itself, and takes one argument, а Ше to Бе 
translated. The file is assumed to contain a sequence of forms, which are read in, translated, and 
output to a file called file. TRAN. The translation notes are meanwhile output to file: STRAN. Thus 
ће usual sequence for bring a foreign file to Interlisp is as follows: prescan the file; examine code 
and transformations, making changes to the transformations if needed; transor the file; and clean 
up remaining problems, guided by the notes. The user can now make a pretty file and proceed to 
exercise and check out his program. To export a file, it is usually best to transor it, then prescan | 
. it, and perform clean-up on the foreign system where the file can be loaded. 


transor[sourcefile] Translates sourcefile. Prettyprints translation on file. TRAN: 
| translation listing оп file. 5ТКАМ. 


transorform[form] Argument is a LISP form. Returns the (destructively) translated 
| | form. The translation listing is dumped to the primary output file. 


transorfns[fnlst] Argument is a list of function names whosc interpreted definitions 
| are destructively translated. Listing to primary output file. 


transform and transorfns can be used to translate expressions that are alrcady in core, whereas 
transor itsclf only works on files. | ! 
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THE TRANSLATION NOTES 


The translation notes are a catalog of changes made in the user’s code, and of problems which 
require, or may require, further attention from the user. ‘This catalog consists of two cross-indexed 
sections: an index of forms and an index of notes. ‘The first tabulates all the notes applicable to 
any form, whereas the second tabulates all the forms to which any one note applies. Forms appear 
in the index of forms in the order in which they were encountered, 1.е. the order in which they 
appear on the source and output files. The index of notes shows the name of each note, the entry 
numbers where it was used, and its text, and is alphabetical by name. The following sample was - 
made by translating a small test file written in SRI LISP. 


LISTING FROM TRANSORING OF FILE TESTFILE.;7 
DONE ON 1-NOV-71 20:10:47 


| INDEX OF FORMS 
1. APPLY/EVAL at 
[DEFINEQ | 
(FSET (LAMBDA & 
(PROG ...3... 
| (SETQ Z (COND 
((АТОМ (SETQ --)) 
(COND 


((АТОМ (SETQ Y (NLSETQ "(EVAL и)" ))) 


2. APPLY/EVAL at 
[DEFINEQ 
(FSET (LAMBDA & - 
(PROG ...3.... 
. (SETQ 2 (COND 
| (Саток. (ЅЕТО =). 
(соно 


((АТОМ (5ЕТО --)) 
"(EVAL (NCONS W))") 


--)) 
--)) 
23. MACHINE-CODE at 
ГОЕЕТНЕО 
(LESS1 (LAMBDA 4 
(PROG ...3... 
(COND 
Ме NE 
((NOT (EQUAL (SETQ Х2 "(OPER (MAKNUM & -))" 
) 
--)) 
--)) 
4. MACHINE-CODE at 
[DEFINEQ 
(LESS1 (LAMBDA & 
(PROG ...3... 
(COND 
NE SE 


((NOT (EQUAL & (SETQ Y2 
"(OPENR (MAKNUM & --))"))) 


xe 


INDEX OF NOTES 
APPLY/EVAL at 1, 2. | 
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TRANSOR will translate the arguments of the APPLY or EVAL expression, but the user 
must make sure that the run-time evaluation of the arguments returns a BBN-compatible 
expression. | | 
MACHINE-CODE at 3, 4, | 

Expression dependent on machine-code. User must гесоде. 


The translation notes are generated by the transformations used, and therefore reflect the judgment 
of their author as to what should be included. Straightforward conversions are usually made 
without comment; for example, the DEFPROP's in this file were quietly changed to DEFINEQ's. 
transor found four noteworthy forms on the file, and printed an entry for each in the index of 
forms, consisting of an entry number, the name of the note, and a printout showing the precise | 
location of the form. The form appears in double-quotes and is the last thing printed, except for | 
closing parentheses and dashes. An ampersand represents one non-atomic element not shown, and 
two or more elements not shown are represented as ..n.. where n is the number of elements. 
Note that the printouts describe expressions on the output file rather than the source file; in the 
example, the DEFPROP's of SRI LISP have been шы with ВЕРНЕР; 5. | 


ERRORS AND MESSAGES 


transor records its progress through the source file by teletype printouts which identify each 
expression as it is read in. Progress within large expressions, such as a long DE F pus is ро! 
every three minutes by а printout showing the location of the sweep. 


If a transformation fails, transor prints а diagnostic to the teletype which identifies 1 the: faulty 
transformation, and resumes the sweep with the next form. The translation notes will identify the 
form which caused this failure, and the extent to which the form and its arguments were 
compromised by the error. | 


If the transformation for a common function fails fépeatediy, the user can type control-H. When 
the system goes into a break, he can use transorset to repair the transformation, and even test it 
out (see TEST command, page 24.26). He may then continue the main translation with OK. 


TRANSORSET 


To use . transorset, type transorset() to Interlisp. transorset will respond with a + sign, its prompt 
character, and await input. The user is now in an executive loop which is like evalgt with some 
extra context and capabilities intended to facilitate the writing of transformations. transorset will 
thus progress apply and eval input, and execute history commands just as evalgt would. Edit 
commands, however, are interpreted as additions to the transformation on which the user is 
currently working. transorset always saves on a variable named currentfn the name of the last 
function whose transformation was altered or examined by the user. currentfn thus represents the 
function whose transformation is currently being worked on. Whenever edit commands are typed 
to the + sign, transorset will add them to the transformation for currentfn. This is the basic 
mechanism for writing a transformation. In addition, transorset contains commands for printing 
out a transformation, cditing a transformation, etc., which all assume that the command applies to 
currentfn if no function is specified. The following example illustrates this process. 


-TRANSORSET( ) О 

+ЕМ TCONC | [1] 
TCONC 2 

+(SW 2 3) [?] 
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+TEST (TCONC A B) | [3] 


P 
(TCONC B A) 
«TEST (TCONC X) [4] 
J TRANSLATION ERROR: FAULTY TRANSFORMATION 
TRANSFORMATION: ((SW 2 3)) |. [5] 
OBJECT FORM: (ТСОМС X) 


1. TRANSFORMATION ERROR TO Геј 
"(TCONC X)" 


.(TCONC X) h 
_ +(ТЕ (## 3) ((SW 2 3)) (С 2 NIL] [7] 
*SHOW. | | 
TCONC | 
[(SW 2 3) 2E 
(IF (зу | | | [8] 
((SW 2 3)) | 
. ((с2г NIL] 
TCONC | | 
+ERASE _ | | | | [9] 
TCONC | 
+REDO IF Р [10] 
. +SHOW | Е | 
ТСОМС 
Г(ТЕ (## 3) 
((SW 2 3)) 
((-2 NIL] 
 ТСОМС 
+TDST | | 
=TEST | | | » [11] 
ыы NIL Х) | | 


In this sanie the user begins by using the FN command to set currentfn to TCONC "ny He then 
adds to the (empty) transformation for tconc a command to switch the order of the arguments [2] 
and tests the transformation (3).- His second TEST [4] fails, causing ап error diagnostic [5] and a 
translation note [6]. He writes a better command [7] but forgets that the original SW command is 

Still in the way [8]. He therefore deletes ne entire transformation [9] and redoes the IF [10]. This 
time, the TEST works [11]. 


TRANSORSET COMMANDS · 


The following commands for manipulating transformations are all lispxmacros which treat the rest 
of their input line as arguments. АП are undoable. 


FN Resets currentfn to its argument, and returns the new value. In 
effect FN says you are done with the old function (as least for the 
moment) and wish to work on another. If the new function already 
has a transformation, the message (OLD TRANSFORMATIONS) is 
printed, and any editcommands typed in will be added to the end · 
of the existing commands. FN followed by a carriage return уш 
rcturn the value of currentfn without changing it. 


24.25 


Section 24: Lispusers Packages 


SHOW Command to prettyprint a transformation. SHOW followed by a 
carriage return will show the transformation for currentfn, and - 
return currentfn as its value. SHOW followed by one or more 
function names will show each one in turn, reset currentfn to the 
last one, and return the new value of currentfn. . 


EDIT | Command to edit a transformation. Similar to SHOW except that 

jn | instead of prettyprinting the transformation, EDIT gives it to edite. 
The user can then work on the transformation until he leaves Ши the 
editor with ОК. | 


ERASE . Command to delete a transformation. Otherwise similar to SHOW. 


TEST Command for checking out transformations. TEST takes one 
i argument, a form for translation. The translation notes, if any, аге | 
printed to the teletype, but in an abbreviated format. which omits 
the index of notes. The value returned is the translated form. 
TEST saves a copy of its argument on the free variable testform, 
and if no argument is given, it uses testform, i.e. tries the previous 

test again. 


DUMP | 222 Command to save your work on а Ме. DUMP takes опе argument, 
a filename. The argument. is saved on the variable dumpfile, so 
that if no argument is provided, a new version of the previous file 
will be created. 


The DUMP command creates files by makefile. Normally fileFNS will be unbound, but the user 
may set it himself; functions called from a transformation by the E command may be saved in this . 
way. DUMP makes sure that the necessary command is included on the fileVARS to save the user's. 
transformations. The user may add anything else to his fileVARS that he wishes. When a 
transformation file is loaded, all previous transformations are erased unless the variable merge is set 
to T. | | | 


EXIT 0 | transorset returns NIL. 


THE REMARK FEATURE 


The translation notes are generated by those transformations that are actually executed via an 
cditmacro called REMARK. REMARK takes one argument, the name of a note. When the macro is. 
executed, it saves the appropriate information for the translation notes, and adds one entry to the 
index of forms. The location that is printed in the index of forms is the editor’s location when the 

REMARK macro is executed. | Е 


To write а transformation which makes а new note, onc must therefore do two things: define the 
note, i.c. choose a new name and associate it with the desired text; and call the new note with the 
REMARK macro, i.c. insert the edit command (REMARK пате) in some transformation. The NOTE 
command, described below, is used to define a new note. The call to the note may be added to a 
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transformation like any other edit command. Once a note is defined, it may be called from as . 
many different transformations as desired. 


The user can also specify a remark with a new text, without bothering to think of a name and 


perform a separate defining opcration, by calling REMARK with more than one argument, e.g. 
(REMARK text-of-remark). This is interpreted to mean that Ше arguments are the text. 
transorset notices all such expressions as they are typed in, and handles naming automatically; a 
new name is generated?’ and defined with the text provided, and the expression itself is edited to 
be (REMARK generated-name). The following example illustrates the use of REMARK. | | 


«ТВАМ50В5ЕТ() Е | 
«NOTE GREATERP/LESSP (BBN'S GREATERP AND LESSP ONLY а 
TAKE TWO ARGUMENTS, WHEREAS SRI'S FUNCTIONS TAKE АМ | 


INDEFINITE NUMBER. АТ THE PLACES NOTED HERE, THE SRI CODE. 


USED MORE THAN TWO ARGUMENTS, AND THE USER MUST RECODE. 1 
GREATERP/LESSP 

*FN GREATERP 

GREATERP 


-*(IF (IGREATERP (LENGTH (##))3) NIL ((REMARK GREATERP/LESSP] [2] 


+FN LESSP 
LESSP | | | | | 
+REDO IF | | [3] 
+SHOW | | | 
LESSP 
[CIF (ІбКЕАТЕВР (LENGTH (йя)) 
| | 3) 


NIL | 

.... ((REMARK GREATERP/LESSP] 
LESSP 

*FN ASCII 


(OLD TRANSFORMATIONS) 
ASCII | 


+(REMARK ALTHOUGH THE SRI FUNCTION ASCII IS IDENTICAL . [4] 
TO THE BBN FUNCTION CHARACTER, THE USER MUST MAKE SURE THAT 
THE CHARACTER BEING CREATED SERVES THE SAME PURPOSE ON BOTH 
SYSTEMS, SINCE THE CONTROL CHARACTERS ARE ALL ASSIGNED / 
DIFFRENTLY. 1 
+SHOW | | | | [5] 
ASCII | | 
((1 CHARACTER) 
(ВЕМАВК А5СТТ:)) 
ASCII | | "E | 
+NOTE ASCII: “| | | z [6] 
EDIT | | | | 
*NTH -2 


. ASSIGNED DIFFRENTLY.) 
“(2 DIFFERENTLY. ) 

OK 

ASCII: 

+ 
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The name generated is the valuc of currentfn suffixed with a colon, or with a number and a colon. 
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In this example, the user defines а note named GREATERP/LESSP by using the NOTE command - 
[1], and writes transformations which call this note whenever the sweep encounters a GREATERP or 
LESSP. with more than two arguments [2-3]. Next, the implicit naming feature is used [4] to add a 
REMARK command to the transformation for ASCII, which has already been partly written. The 
user realizes he mistyped part of the text, so he uses the SHOW command to find the name chosen 
for the note [5]. Then he uses the NOTE command on this name, ASCII:, to edit the note [6]. — 


NOTE | _ First argument is note name and must be a literal atom. If already 
.. defined, NOTE edits the old text; otherwise it defines the name, 
reading the text either from the rest of the input line or from Ше 
next line. The text may be given as a line or as a list. Value is 
name of note. 5 


The text is actually ѕіогей.38 as a comment, i.e. а * and %% are added in front when the note is 
first defined. The text will therefore be lower-cased the first time the user DUMPs (see Section "e 


DELNOTE | . Deletes a note completely (although any calls to it remain in the | 
| transformations). - | 


CONTROLLING THE SWEEP 
transor’s sweep searches in print-order until it finds a form for which a micas exists... The 


location is marked, and the transformation is executed. Тһе sweep then takes over again, | 
beginning from the marked location, no matter where the last command of the transformation left 


_ the editor. User transformations can therefore move around freely to examine the context, without 


worrying about confusing the translator. However, there are many cases where the user wants his . 
transformation to guide the sweep, usually in order to direct the processing of special forms and - 
FEXPR's. For example, the transformation for QUOTE has only one objective: to tell the sweep to 


skip over the argument to QUOTE, which is (presumably) not a LISP form. NLAM is an editmacro "m 


to permit this. 


МАМ An atomic editmacro which sets а flag which causes the sweep to 
| skip the arguments of the current form when the sweep resumes. 


Special forms such as cond, prog, selectq, etc., present a more difficult Бой: For example, 
(COND (A B)) is processed just like (ЕОО (А B)): Те. after the transformation for cond 
finishes, the sweep will locate the "next form," (A B), retrieve the transformation for the function 
A, if any, and execute it. Therefore, special forms must have transformations that preempt the 
. sweep and direct the translation themselves. The following two atomic editmacros permit- such 
transformations to process xd forms, каналына or skipping over arbitrary subexpressions as 
desired. 


38 on the global list usernotes. 


24.28 


Transor 


DOTHIS Translates the editor’s current expression, treating it as a single 
form. 

DOTHESE Translates the editor’s current expression, treating it as a list of 
forms. 


For example, a transformation for setq might be (3 DOTHIS ).2? This translates the second 
argument to а setq without translating the first. For cond, one might write 
(1 (LPQ NX DOTHESE)), which locates each clause of the COND in turn, and translates it as a 
list of forms, instead of as a single form. 


Тһе user who is starting a completely new set of transformations must begin by writing 
transformations for all the special forms. To assist him in this and prevent oversights, the file 


< LISP >SPECIAL.XFORMS contains a set of transformations for LISP special forms, as well as- 


some other transformations which should also be included. The user will probably have to revise 
these transformations substantially, since they merely perform swecp control for Interlisp, i.e. they 
make no changes in the object code. They are provided chiefly as a checklist and tutorial device, 


since these transformations are both the first to be written and the most difficult, especialy for 


users new to the Interlisp editor. 

When the sweep mechanism encounters a form which is not a list, or a form car of which is not an 
atom, it retrieves one of the following special transformations. 

NLISTPCOMS | : Global value is used as a transformation for any form which is not 


a list. 


For example, if the user wished to make sure that all strings were quoted, he might set nlistpcoms 
to ((ТЕ (STRINGP (##)) ((ORR ((* QUOTE))((MBD QUOTE)))) NIL)). 


LAMBDACOMS Global value is used as a transformation for any form, car of which - 


is not an atom. 


These variables are initialized by <LISP>SPECIAL.XFORMS and are saved by the DUMP- 


command. nlistpcoms is initially NIL, making it a NOP. lambdacoms is initialized to check first 
for open LAMBDA expressions, processing them without translation notes unless the expression is 
badly formed. Any other forms with a non-atomic car are simply treated as lists of forms and are 
always mentioned in the translation notes. The user can change Or add to this algorithm simply by 
editing or resetting lambdacoms. | 


This completes the discussion of TRANSOR. 


39 


Recall that a transformation is a list of edit commands. In this case, there аге two commands, 3 and DOTHIS. 
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24.5 INDEXING AND CROSS REFERENCING FILES 


MULTIFILEINDEX™ 


Many systems built in Interlisp consist of a number of symbolic source files. Finding one's way 


around in the listings for these various files can be very tedious, even for the implementor of the - 


system. The multifileindex package is an attempt to help users deal with this problem by creating - 
a listing of an entire system or set of files, including an alphebetized table of contents containing 


entries for cach function on any of the files. Information is also included for other entities in the | 


files such as records, blocks, and properties. The function multifileindex implements this 
mechanism. | | | 


multifileindex first creates an alphabctized table of contents, indicating the name of the entity, the 
file that it belongs to, and its type (property, variable (set or saved), record, block, etc.) in a 


columnar format. If the entity is the name of a function, then the information also includes a 


unique index іп the listing for the function, its function type, and its arguments. The files are then. 
printed with each function being preceeded by its indexnumber right-justified on the line. Header | 
information is placed at the top of each page, and the pages are numbered. After the files have | 

been listed, they are (undoably) removed from notlistedfiles. 


multifilindexffilenamets mapfile;newpageflg] 

filenamelst can either be a list of file names, or an atom. If 
filenamelst is NIL, multifileindex returns immediately. If it is T, 
filelst is used. multifileindex requires that the COMS for all the files 
being listed need to be loaded. If a particular file is not loaded, *? 

then its fileCOMS will not be set. In this case, multifileindex will do 
a loadvars on the file to load the fileCOMS. (Note that this may _ 
have other side effects.) | 


mapfile is the output file. If mapfile is NIL, it defaults to value the 
of printer (initially LPT:). If newpageflg = T, each function in the 
listing will be placed on a page by itself. 


The value of linesperpage determines the number of lines per page, and is initially 58. The value 
of filelinelength determines the width of the page. The following four parameters affect how the - 
columns are placed. The value of multifileindexcols indicates how the other three аге to be 
interpreted. These other variables are  multifileindexnamecol,  multifilcindexfilecol, and 


 multifileindextypecol (initally 0, 26 and 41, respectively). If multifileindexcols is the atom - 


FLOATCOLS (its initial valuc), then an attempt is made to fit the columns onto the page in a way 
that maximizes the amount of space for the type information (the amount of space allocated for the 
type Пеја must be at least 45% of filelinclength in this case). If multifileindexcols is either T or 


40 — multifileindex was written by J. J. Vittal. It is contained on the file MULTIFILEINDEX.COM. 
ч  multifileindex assumes if fileCOMS is set, then all nested or indirect COMS are also set. 


4 or it was loaded with the SYSLOAD option to load. 
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FIXCOLS, then the value of the other variables are treated as absolute column positions on the 


page. If multifileindexscols is cither NIL or FIXFLOATCOLS, the columns will be floated, but will 
not be any smaller than the column positions defined by the other variables. 


SINGLEFILEINDEX? 


singlefileindex is a package for giving the user an alphabetical function index on the front of each 
lisp file listed by Interlisp. This package is similar to the multifileindex package described above, 
except that singlefileindex provides a table of contents for functions only, and operates on one file 
at a time. However, Singlefilcindex is much simpler and faster than multifileindex and is useful 
every time a file is made. 


The first page gives the filename, time of creation, and the time of the listing. Following that (on 
possibly more than one page) are n columns of function names and index numbers, where the 
index number indicates the function’s linear occurrence within Ше file. The number of columns is 


. determined by the length of the longest function name, as well as by the number of functions in - 


the file as described below. The file is then printed with the filename and page number at the top 
of every page, and each function is Оди by its index number right-justified on Ше Page. 


When the singlefileindex package is first loaded, it redefines listfiles] (Section 14) so that all files 


listed by listfiles will be listed using 5 singlefileindex.^^ Note that the file being indexed does not 
have to be loaded, or even noticed in the file package s sense. 


singlefileindex[file; outputfile; newpageflg] 
file is the lisp source file. outputfile is the destination file. If 


outputfile — NIL, then the value of printer (initially LPT:) is used. 


newpageflg = T means each function will be printed on а new page. 
The value of filelinelength determines the position of the index 


numbers, as well as the placement of the columns. The value of | 


linesperpage (initially 58) determines the number of lines per: page. 


24.6 DATABASEFNS^ 


databasefns is a very small package whose purpose is to make the construction and maintenance of 
Masterscope databases an essentially automatic process. It modifies makefile, load, and loadfrom to 
behave in the following way: | | 


СА database will be maintained automatically for any file (containing functions) whose file name has 


the property DATABASE with value YES. Whenever such a file is dumped via makefile, 
masterscope will analyse any new or changed functions on the file, and a database for all of the 


43 singlefileindex was written by M. D. Yonke. It is contained on the file SINGLEFILEINDEX.COM 
44 with both outputfile and newpageflg being NIL. 
45 


The databasefns package was written by К. M. Kaplan. It is contained on the file DATABASEFNS. СОМ. 
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functions on the file will be written on a separate file whose name is of the form file.DATABASE. 


Whenever a file which has a DATABASE property with value YES is loaded via load or loadfrom, 


then the corresponding .DATABASE file, if any, is also loaded. The database will not be dumped 
or loaded if the value of the DATABASE property for the file is NO. ^6 


If the DATABASE property is not YES or NO, then for makefile, load, and loadfrom will ask the 
user whether he wants automatic database maintenance." Thus when a file is dumped for the first 
time, the user will be asked "Do you want а Masterscope Database for this file?". Similarly, if the 
user loads a file which has an associated database, the user will be asked "load database for 


< file > ?". 


The above шеге тау ре controlled ма the global variables savedbflg and loaddbflg. When a 


Не which has neither a YES or NO database property is being dumped, makefile will assume (and 


store) a YES value if the value of savedblfg is YES, and a NO value if s savedbflg is NO. The user 
will be queried only if savedbflg is ASK (its initial value). Similarly, if loaddblfg is YES, load and 
loadfrom will automatically load an existing . DATABASE file for a file which does not have a YES 


or NO value for its DATABASE property. The database will not be loaded if loaddbflg is NO, and 


the user will be interrogated as described above if loaddbflg is ASK (its initial value). . 


The user can dump and restore databases explicitly via the following functions: 


dumpdb[file] — .. dumps a database for file then sets the DATABASE property to YES, 


. SO that database maintenance for Ше vill а а бе 
automatic. | 
loaddb[file] | .. loads the Ме file. DATABASE if one exists. After the database is 


loaded, the DATABASE property for file is set to YES, so that 
maintenance will thereafter be automatic. 


Database files include the date and full filename of the file to 

_ which they correspond. loaddb will print out a warning message if 
it loads a database that does not correspond to the in-core version 
of the file. 


Note that loaddb is the only approved way of loading a database: 
Attempting to load a database file will cause an error. 


24.7 LAMBDATRAN® 


The purpose of this package is to facilitate defining new lambda words in such a way that a variety 


of other system packages will respond to them appropriately. A lambda word is a word that can 


46 Тһе DATABASE property is considered to be NO if the file is loaded with Idflg=SYSLOAD. 
47 — The user's answer will be stored оп the DATATBASE property so that he will not be asked again. . 


48 The lambdatran package was written by R. M. Kaplan. It is contained on the Пе АМВОАТКАМ. СОМ, 
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appear as car of a function definition, like LAMBDA and NLAMBDA. New lambda words are useful 
because they enable the user to define his own conventions about such things as the interpretation 
of arguments, and to build in certain defaults about how values are returned. For example, the 
decl package (page 24.53) defines DLAMBDA as a new lambda word with unconventional 
arguments such as the following: 


(DLAMBDA ((A FLOATP) (B FIXP) (RETURNS SMALLP)) (FOO A B)) 


In order for such: an expression to be executable and compilable, a mechanism must be provided | 


for translating this expression to an ordinary LAMBDA or NLAMBDA, with the special behavior 


associated with the arguments built into the function body. The lambdatran package accomplishes . 


this via an appropriate entry on dwimuserforms (see Section 17) that computes the translation. 


Besides executing and compiling, Interis applies a number of other operations to function 
definitions (e.g. breaking, advising), many of which depend on the system being able to determine 
certain properties of the function, such as the names of its arguments, their number, and the type 
of the function (EXPR, FEXPR, etc.). The lambdatran package also provides new definitions for 
the functions fntyp, arglst, nargs, and argtype which can be told how to compute a for the 
user’s Н Кенес 


А new lambda-word is defined іп the following way: 


1. Add the lambda-word itself (e.g. the atom DLAMBDA) to the list 1 ambdasplst. This suppresses 
attempts to correct the spelling of the lambda-word. 


2. Add an entry for the lambda-word to the association-list . lambdatranfns, Wa is a list of 


elements of the form: (Lambda-word Tranfn Fntyp Arglist), where. 
lambda-word is the name of the lambda-word (e.g. DLAMBDA). _ 


tranfn is a function of one argument that will be called whenever a 
real definition is needed for the lambda-word definition. Its 
argument is the lambda-word definition, and its value should be a 
conventional LAMBDA or NLAMBDA expression which will become 
the translation of the lambda-word form. The free variable faultfn 
is bound to the name of the function in which the lambda-word 
form appeared (or TYPE-IN if the form was typed in). 


fntyp determines the function-type of a definition beginning with 
lambda-word. It is consulted if the definition does not already have 
a translation from which the function type may be deduced. If 
fntyp is one of the atoms EXPR, FEXPR, EXPR*, FEXPR*, then 


all definitions beginning with lambda-word are assumed to have 


that type. Otherwise, fntyp is a function of опе argument that will 
be applied to the lambda-word definition. Its value should be one 
of the above four function types. 


arglist determines the argument list of the definition if it has not 
already been translated (if it has, the arglist is simply thc arglist of 
the translation). It is also a function of one argument, the 
lambda-word definition, and its valuc should be the list of 
arguments for the function (e.g. (А B) in the DLAMBDA example 
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above) If the lambda-word definition is ill-formed and the 
argument list cannot be computed, the function should return T. If 
an arglist entry is not provided in the lambdatranfns element, then 
the argument list defaults to the second element of the definition. 


As an example, the lambdatranfns entry for DLAMBDA is (DLAMBDA DECL EXPR 
DLAMARGLIST), where decl and dlamarglist are functions of one argument. 


Note: if the lambda-word definition has an argument list with argument names appearing cither as 
literal atoms or as the first element of a list, the user should also put the property INFO with value 
BINDS оп the property list of the lambda-word in order to inform dwimify (Section 23) to take 
notice of the names of the arguments when dwimifying. 


24.8 PERMSTATUS® 


The function permstatus defined in this package can be used in conjunction with the зен 
package (Section 14) to make а Ме "permanently" open іп the sense that as much of its status as 
possible will be restored when a sysout is resumed. This includes its access mode, file-pointer 
position, bytesize, and any pages mapped іп by the pmap package. The desired effect is achieved | 
by saying (WHENCLOSE filename 'STATUS S RERNS TATUS) after the file has been opened. 


Note that the permanency of files is not guaranteed in that files may be deleted or renamed, or 
their contents changed, despite their permanent attribute in some sysout. When restarting a sysout, 
a warning message will be printed if the file cannot be found or restored. However, permstatus 
will not be able to detect that the contents of a file have been modified since the sysout was 
created. Note also that "permanent" files will still be closed by closef, and will not be immune to 
closeall or to closing on end-of-file errors unless the appropriate whenclose attributes for closeall 
and EOF аге also established. 


24.9 WHEREIS® 


| This package extends the function whereis (see Section 14) such that, when asked about a given 


name as a function, whereis will consult not only the commands of files that have been noticed by 
the file package (Section 14) but also a hashfile database (page 24.47) that associates function 
names with filenames. 


whereis[name;type;files;-] behaves exactly like the definition in Section 14 unless type=FNS 
(ог NIL) and files— T. In this case, whereis will consult, in addition 
to the files on filelst, the hashfile that is the value of whereis.hash 
(initially <LISPUSER>WHEREIS.HASH). 


Note: most system functions call whereis with files=T, so loading this package automatically makes 
the information contained in the whereis database available throughout the system. 


49 The permstatus package was written by R. M. Kaplan. It is contained on the Ме PERMSTATUS . COM. 


50 The whereis package was written by L. M. Masinter. It is contained оп the file WHEREIS.COM. 
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Information may be added to a whereis hashfile by explicitly calling the following function: 


whereisnotice[filegroup;newflg] inserts the information about all of the functions on the files in 


filegroup into the whereis data base contained on (the value of) 
whereis.hash. filegroup is given as а filegroup argument to 
directory (see Section 21), so &, $, etc. may be used. If newflg=T, 


a new version of whereis.hash will be created containing the - 


database for the functions specified in filegroup. 


Note the whereis package requires the hash package (page 24.47). Loading WHEREIS.COM will 
also load HASH СОМ, if it has not already been loaded. 


24.10 CJSYS?! 


This package provides assistance to Interlisp-10 users who wish to make direct calls on Ше 
operating system (via JSYSes). It also makes the coding of certain common assemble constructions 
more convenient. The package defines the following functions: | 


js[isysname;acl;ac2;ac3;result] nlambda function.. АП arguments are evaluated except for 
jsysname. Like jsys (see Section 21), loads the unboxed values of 
acl, ac2, and ac3 into the appropriate registers, and executes the 


JSYS jsysname. js differs from jsys in that the JSYS may Бе. 


indicated by its PARN name, not just by its number. 52 is also 
generates slightly cleaner code than jsys. js also differs from jsys in 
that: 


(a) if any argument is supplied as NIL, then it is not loaded at all, | 


ie. the corresponding ac will contain garbage. (jsys loads the ac 
with 0 


(b) if result is NIL, then no value is loaded (interpreted, js returns 
the string "garbage result from JS"). 


(c) result can be T, meaning return T if the JSYS skips, NIL if not. 


Because of these differences, caution must be exercised in turning 
jsys calls into js calls. | 


Examples: (JS BIN (ОРМЈЕМ FILE) NIL NIL 2) returns the value of AC2 after doing a BIN | 


from the JFN of file. (JS BOUT (OPNFJN FILE) 3) sends a control-C to file. The value of 
this js call is garbage. 


51 The cjsys package was written бу L. M. Masinter. It is contained on the Ше СЈ5У5.СОМ. | 


52 
not found, then the file STENEX.MAC (ог SYS: MONSYMS.MAC for Tops-20) is scanned. 
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xwd[n1;n2] ^ . . returns (LOGOR (LLSH n1 18) (LOGAND n2 7777770) ), i.e. 
| | ~ the word with nl in the left half and n2 in Ше right. 


БРКА ;word] — =- lambda no-spread. If word is not specified, bit simply returns а 

"a | . number with bit ЫЕ set to 1 and ай other bits 0. If word is 
given, then bit is а predicate that returns T if bit# is set in word. 
Bits are numbered from left to right. 


кыш (BIT 32) is 8 (=10Q), (BIT 32 8) i is T. 


jsyserror[errorn] nlambda function. Returns the TENEX/TOPS- 20 error number 
| | for errorn. For example, (JSYSERROR А) 15 е 
jsyserror compiles open as a constant. — 


This package also defines the following assemble macros: 


(JS jsysname) | càn be used in assemble statements instead of (JSYS jsysnumber) 

(СМ ехр) expands to (СО (VAG (FIX expr))), which unboxes ехрг to AC1. 

(CV2 expr) expands to (CQ2 (VAG (FIX expr), which unboxes е expr to AC2, 
saving АС1. 


24.11 SCRATCHLIST 


This facility helps in writing programs that wish to reuse a scratch list to collect together some 
result. 


There are two functions (both of which compile open): 


scratchlist[lst;x 4 x»;...:x |] nlambda, nospread. scratchlist sets up a context in which the value 
of Ist is used as a "scratch" list. The expressions Xj, хр, .. Xp are 
evaluated in turn. During the course of evaluation, any value passed 
to addtoscratchlist will be saved, rcusing cons cells from the value 
of Ist. If the value of Ist is not long enough, new cons cells will be 
added onto its end. If the valuc of Ist is NIL, the entire value of 
scratchlist will be "new" (i.e. no cons cells will be reused). 


addtoscratchlist[value] For use under calls to scratchlist. value is added on to the end of 
the value being collected by scratchlist. When scratchlist returns, its 
value is a list containing all of the things that addtoscratchlist has 
added. 
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24.12 NOBOX? 


This package contains facilities for subverting the normal manner of dynamically allocating and 
collecting cons cells, large integer boxes, and floating boxes in Interlisp-10 by using static, compile- 
time allocation. Storage allocation is controlled by allocating the memory for temporary results 
(e.g. a list that will be thrown away or a floating number that will not exist outside a local 
computational context) at compile-time or load-time. This “static” storage will be reused whenever 
the given line of code is re-executed. Because functions which use these facilities may exhibit 
bizarre behaviour if they are called recursively or if values escape outside of them, these facilities 
must be used with extreme caution, and should be reserved for those cases where the normal 
method of storage allocation and garbage collection is not workable or practical. Note: compiled 
.functions need no run-time support for these facilities, i.e. NOBOX does not have to be loaded to 
execute compiled code. | 


CONS CELLS 


The function cbox may be used to avoid allocation of cons cells. When run interpreted, cbox is 
exactly equivalent to the function cons. Compiled, cbox operates like cons, except that the cons cell 
returned is constructed (once) at compile or load time. New values for car and cdr are smashed 
into the cell at each execution. 


The function Ibox performs an analagous role for list. When run interpreted, Ibox is exactly 
equivalent to list. Compiled, the corresponding cons cells are allocated at compile or load time. 
For example, (LBOX A B C) will cause a 3-element static list to be included with a compiled 
function’s literals. Each time the corresponding compiled code is executed, those three cells will be 
returned containing the current values of the variables a, b, and c. | 


Ibox allocates as many cells as there are arguments іп the corresponding form, i.e. the number of 
scratch cells is determined at compile time. The iterative statement operator SCRATCHCOLLECT 
enables avoiding conses when Ше length of a list is not known at compile-time. 
SCRATCHCOLLECT is used in iterative statements exactly as COLLECT. Each time it is executed, it- 
reuses the cells that it returned on previous executions, which it remembers as an internal scratch 
list. The length of this scratch list is always the length of the longest value that was ever returned; 
new cells are allocated whenever the scratch list runs out, and they are permanently remembered. 


The SCRATCHCOLLECT is.opr and the function scratchlist (page 24.36) have similar applications. 
With scratchlist, the user makes explicit the origin of the list getting smashed, while with the 
SCRATCHCOLLECT 1.5.орг, the scratch list is hidden (and there is a different scratch-list for each 
occurence of the i.s.opr). 


NUMBER BOXES 
The functions ох, Фох, and nbox, and the record declarations IBOX and FBOX are provided to 


improve Ше efficiency of arithmetic computations. They permit information to be given to the 
Interlisp-10 compiler that will inhibit the allocation (and subsequent collection) of number boxes 


53 The МОВОХ package was written by К. М. Kaplan with assistance from В. A. Sheil апа М. Kay. It is contained оп 


the file NOBOX . СОМ, 
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needed for holding temporary results of numeric computations.4 In addition, access time to 
variable-values that are known to be large integers or floating point numbers is improved. 


The records IBOX and FBOX essentially describe the structure of large integer and floating point 
boxes respectively. IBOX consists of a single field, called I, which corresponds to the actual 
contents of the large integer box. FBOX consists of a single field, called F, which corresponds to 


the contents of the floating point box. For example, the user can create a large integer box 


containing a given value and assign it to x by saying (SETQ X (create IBOX I * Ѓогт)). 
Even if the value of form is a small integer, the result will be stored in a new, large number box. 
This seeming inefficiency is important because if some values of form might be large, making all 
values large means that the compiler can be told how to treat all references to x without generating 
run-time tests to discover how to do the unboxing. Thus, wherever the value of x is to be 
referenced, the user simply writes X:I (or (fetch I of X)). In compiling this expression, the 
compiler generates a single MOVE instruction without any type-testing whatsoever. The user can 
reuse that number box by saying Х:Те(ЕОО), which is equivalent to, but much more efficent . 
than, (SETN X (Ғ00)). In other words, once it is known that x is bound to a large integer, the 

suffix :[ can be used in all number-contexts to inform the compiler of that fact. 


The facilities described so far do nothing to suppress the creation of unnecessary boxes; indeed, the 


(create IBOX --) will produces boxes for small numbers that would not be allocated otherwise. 
The functions (not records) ibox, fbox, and nbox are used to suppress unnecessary boxing of 


-temporaries. Effectively, they cause "constant" or "static" boxes of the appropriate type to be 


allocated and stored in a function's literals when a function is compiled or loaded. Those boxes 
can be used (and reused) to hold temporary results. | 


ibox and fbox can be called with 0 or 1 arguments. If no arguments are specified (as opposed to a 
single argument whose value is NIL), then the value of the function is a large-integer or floating 
number box which is allocated statically. For example, these might be used to construct an initial 
binding for a variable into which temporary values will be stored using the :I or :F assignments. 
For example: | | 


(PROG ((Х (1В0Х))) (X:Ie(F00)) ...). 


If an argument is specified for ibox or fbox, then a static box of the appropriate type will be 
allocated at compile- or load-time, and the value of the argument will be stored in that box 
whenever the IBOX statement is executed. For example, suppose the user wanted to set a file 
pointer to 1 past a given byte position. The expression 


(SETFILEPTR FILE (ADD1 POS)) 
would generate a new number box on each execution for which pos happened to be a large 
number. That box would be passed into setfileptr and then returned as its value. Since the value 
is not saved, the box would be thrown away, to be collected later. The expression 


(SETFILEPTR FILE (IBOX (ADD1 Р05))) 


would store the desired position in a constant box, and no allocations would take place. 


54 In the latter respect, these duplicate some of what setn (Section 13) does, except that they аге more convenient to 


use and are executed with less run-time checking (i.e. setn will never smash random memory locations). 
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Nobox 


As another example, consider a complicated integer expression whose value must be saved in a 


(Xe(IPLUS 2000 (ITIMES FOO ( IQUOTIENT FUM 5)))) 

(Ze(IPLUS X (GETFILEPTR FILE))) 
The Interlisp-10 compiler is smart enough to suppress the boxing inside the (IPLUS 2000 &) 
expression, but it will generate a box when it comes to do the $ setq (*). This box can be 
suppressed by writing | 


(Хе(ТВОХ (IPLUS 2000 (ITIMES FOO (IQUOTIENT FUM 5))))) 


Furthermore, since it is known that x is bound to a large integer, the z assignment c can | be speeded 
up by writing 


 (Ze(IPLUS Х:1 (GETFILEPTR FILE))) 


The function fbox behaves the same as ibox, except that it traffics in constant floating boxes. Note. 
that if the argument of ibox is FLOATP, then it will be FIXed; if the argument of Њох is FIXP, it 


will be FLOATed. 


The function aber is a generic function for copying unknown values into constant number boxes. 


It allocates two constant boxes, one integer and one floating, and stores the value of its argument 
in the one compatible with the value’s type. nbox is useful if the argument value is a constant 
number box (but one of unknown type) that needs to be copied (see caution (2) below). 3 


CAUTIONS 


There are some dangers in using these facilities. The user of this package should be particularly 
aware of the following: 


(1) The F and I fields aim at efficiency more than validity. This means that they do not check 


the type of the pointer that they smash into. For example, if x is bound to NIL, the expression 
Х:1+7 will clobber car and cdr of NIL! The user must be very careful that the arguments given 
for replacing do indeed point to cells that unboxed numbers сап be smashed into. Note: the decl 
package (page 24.53) can be used to generate the replaces, iboxes, fboxes automatically in a safe 
and efficient way. 


(2) cbox, Ibox, SCRATCHCOLLECT, ibox, and fbox all allocate constant boxes, and those boxes will 
be reused (ie. smashed with new values) every time the code containing that function call is 
executed. If that box is saved in a variable or data-structure (e.g. by а setq) as а way of preserving 
the value it contains, and then the code is re-executed, the value that was saved will be smashed. 
Thus, the user must beware of using constant boxes to save information in loops or recursions that 
сап get back to the same statement. In these situations, the values must be copied into other cells, 
perhaps a constant associated with some other line of code, or into cells allocated in the ordinary 
way. The user must also be careful about returning a constant box as the value of a function, since 
the caller might unknowingly save the value and re-invoke the box-returner. 


(3) because the constant boxes are allocated only in compiled code, these functions will work quite 
differently compiled and interpreted. Side effects which occur because of inadvertent smashing of 
shared structures will only occur when running compiled definitions and will not be detectable 
when running interpreted. | 
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24.13 DATEFORMAT” 


dateformat is a small file (one function) which provides assistance for constructing format bits for 
the ODTIM JSYS (output date/time) as required by date and gdate. dateformat is given a set of 
keywords (listed below) and it returns a number suitable as a parameter to date and gdate. 
dateformat is an NLAMBDA NOSPREAD function. The keywords are given below (usually in pairs) 
and can be thought of as switches (i.e. turn on or off a particular format feature). The default for 
each pair is indicated by an "[*]" after the keyword. If no keyword is given for a particular pair, 
the default is used.?? The variable dateformatkeys is а list of the keywords used for spelling 
correction. | | 2 


The keywords are: 


DATE [*] | Include the date information. 
NO.DATE » Don't include the date information. 
NAME.OF.MONTH [*] Show the month as the name of month. 

NUMBER. ОЕ . MONTH Show the month as the number of the month. 

. MONTH. LONG If the name of the month was requested, spell it out. . 
MONTH. SHORT [*] If the name of the month was requested, abbreviate it. | 
YEAR.LONG Four digit year, e.g. 1978. 
YEAR .SHORT [*] Two digit year, e.g. 78. 
DAY. OF . WEEK | Include the day of the week in the date information. — 
NO.DAY.OF.WEEK [*] . Don't include the day of the week in the date information. 
DAY. LONG If the day of the week was included, spell it out. 
DAY . SHORT [*] If the day of the week was included, abbreviate it. 
DASHES [*] | | Separate the < дау >, <month>, апа <уеаг> fields with dashes. 
SLASHES Separate the < дау >, <month>, and < year» fields with slashes. 
SPACES | Separate the < day >, <month>, and <year> fields with spaces. 
USA.FORMAT | (| The order <month> <day> <year>. 
EUROPE . FORMAT [*] The order < дау > <month> <year>. 
LEADING.SPACES [*] Keep the < day > field two characters long. 
NO.LEADING.SPACES < day > field can be one character for dates earlier than the 10th. 
TIME [*] | Include the time information. 
NO.TIME Don't include the time information. 
TIME.ZONE Include the time zone in the time specification. 
NO.TIME.ZONE [*] Don't include the time zone in the time specification. 


35 The dateformat package was written by M. Yonke. It is contained on the file DATEFORMAT . СОМ. 


56 The variable datcformat.dcfault is the number used as the initial value to work with. Therefore, to switch any of 
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SECONDS [*] 
NO.SECONDS 


CIVILIAN. TIME 
MILITARY. TIME [*] 


24.14 EXEC? 


This file contains a sct of lispmacros (Section 22) which resemble features of the TENEX EXEC. 
It also defines functions that provide certain EXEC capabilities for Interlisp programs, e.g. 


Dateformat 


Include the seconds. 
Don’t include the seconds. 


12 hour time (with AM or PM). 
24 hour time. 


changing the connected directory, detaching the job, etc. 


EXEC LISPXMACROS 


DA 


LD 


LD username 
LD ALL 

DET 

QU 


LINK user 


BR 


prints out current time and date. 


prints systat information, just like the LD subsystem. Jobs are 
sorted | in inverse order of CPU utilization.>8 


prints information for that user only. | 

like LD, but includes system jobs. 

detaches the current job. 

does a logout(). Does not go on history list. 


mimics the exec link command. If user has multiple 1028 logged 1 іп, 
asks which tty to link to. 59 


breaks links. 


57 The EXEC package was written by Г. M. Masinter, D. C. Lewis and J. J. Vittal. It is contained on Ше file 
EXEC.COM. The Exec package uses the passwords package. Loading EXEC. COM will load PASSWORDS .COM if it 
has not already been loaded. Note: some of the facilities described below will work correctly only оп TENEX 
systems, others only on TOPS-20. The system will inform the user when he attempts to use a facility not supported 
by his particular operating system. 


58. 


59 


TALK is a synonym Гог LINK. 


SY and WHE is a synonym for LD. 
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CONN dir pwd 


NDIR filegroup 


DEL filegroup 


UND filegroup 


DELVER filegroup 


EXP dir 


TY file outfile bytesize 


DSK dir days- 


FI 


FIjfn 
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connects to the directory dir. If the password pwd is not given and 
is required, conn will prompt. dir can be abbreviated; if omitted, it 
defaults to the user's login directory. If pwd is given in command | 
line, it is removed from the history list so that ?? will not print it 
out. Password prompting is handled by getpassword from the 
passwords package (page 24.44). 


prints the files in filegroup in a multi-column format. 


deletes specified files. Uses directory. Note. that if < esc> is 


· specified, all files that match will be deleted. This command: 1 is 


undoable. 


undeletes the specified files (undoably). | 


 deletes all but 1 version of the filegroup specified. Uses directory | 


(Section 21), so filegroup may utilize any of the options allowed for | 
directory filegroup specifications. | 


expunges directory dir. 9 


copies file to outfile, or T if outfile is not given. Assumes that the 
bytes of file are bytesize bits wide (bytesize=NIL defaults to 7). 
Suppresses blank lines and control character жшше used to 
indicate font changes.® 


prints out disk allocation and usage for the directory dir using 
dskstat. Also prints total size of files untouched in days d ays (90 if 
days not specified). 


like the EXEC filestat command, prints out status of all currently 
assigned JFNS for the current job. | 


prints information for jfn only. 


If the user does not have access to dir, a message is printed. 


SEE is a synonym for TY. 
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EXEC FUNCTIONS 


job #[] 
tty #[] 
detach[] 


: detachedp[] 


linktotty[tty # | 


linktouser[user] | 


breaklinks[] 

| cndir[dir;password] 
/ delfile[file] 
/undelfile[file] 


expungel[dir] 


. Exec 


returns the job number for the logged іп job. 
returns the teletype-number of the current job. 


detaches the current job. 


a predicate that returns T if the current program is running 


detached. 


generates a two-way link between the controlling terminal of the 
users job and tty#. Returns T if the link was successful, otherwise | 
prints an error message and returns NIL. 


links the controlling terminal to a terminal associated with user. 


Generates an error if the user is not logged in or not attached. If 


user has more than one attached job, then a systat of his jobs is- 
printed, and the user is asked to provide the proper tty number for | 


the job. Returns Т if successful. 


breaks all links to the user’s controlling terminal. 


Implements the conn command. | 


undoable version of delfile. 


undeletes a single file (undoably). 


expunges directory dir. On TENEX, dir is ignored. and the 
connected directory is expunged. On TOPS20, if the user does not _ 


have access to dir, a message is printed. 


copyalbytesfromfi tofile;bytesize] 


implements the sec command. 


dskstat[dir;printifover;printsys;printdcl;printold] 


prints disk usage statistics for directory dir (cither a name or 
number). 
means only print if dir is over allocation printifover a number 
mcans only print if dir has morc than that many pages in use. 
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printsys=T means print system disk statistics too. 


printdel=T means punt total size of deleted files for dir (this is 
slow). 


 printold — T or a number means print total size of files untouched 
in 90 (or printold) days. 


memstat[pgl;pgn;fork] - prints the status of the memory pages pel (0 if реп = NIL) to pgn 
(the last page of memory if NIL) in fork fork. fork is cither NIL, 
. meaning the current fork, or а fork handle. 


24.15 PASSWORDS? 


getpassword[directoryname] | ‘prompts the user for the password for the given directory. The 
в? | | . users response is not echoed. getpassword remembers the 
password so that it need not ask again; however, saved information 

is cleared before sysout, so that the sysout contains no passwords. 


24.16 TELNET? | 
This package makes it possible to interact with connections created via the net package (described 
below) without leaving Interlisp. 


ielneifcantiection type; ке in addition, all typeout is included. in the dribble file. It permits | 
| | connections to ARPANET hosts (a la TELNET). connection тау 
be an instance of a CONNECTION record (as created by 
makenewconnection, see below). Alternatively, the arguments to 
makenewconnection may be specified in the call to telnet (ie. if 
connection is а - litatom, telnet  иѕеѕ 
.. makenewconnection[connection;type;skt] for the connection). In any 
case, telnet returns the connection as an instance of the 
CONNECTION record, so that it is possible to telnet back. 


24.17 FTP“ 


Тһе ftp package makes it possible to deal with files at other hosts on the Arpa network almost as if 


they were files on the user's local machine, i.e. the files can be opened via infile, outfile, openfile, 


62 The passwords package was written by L. M. Masinter. It is contained on the file PASSWORDS . COM. 
63 The telnet package was written by L. M. Masinter. It is contained on the file TELNET.COM, Since the telnet package 
uses the net ГЕ loading ТЕГ МЕТ. COM will also load МЕТ. сом unless it has already been loaded. 


The Пр package was written by L. М. Masinter. It is contained on the file FTP.COM. The Пр package uses Ше net 
and passwords PNE Loading FTP.COM will load NET. COM and PASSWORDS.COM if they are not already 
loaded. 
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Ғір 


read from and printed to by the ordinary reading and printing functions, and closed in the 
standard way. 


Files on remote hosts are designated by including the host name between curly brackets, {}, at the 
front of the ordinary file name. Since curly brackets are illegal characters in regular file names, a 
BAD FILE NAME error is generated. This error is intercepted by an entry on errortypelst (see 
Section 16) which then establishes the appropriate network connections. For example, 
infile[ {BBN - D}<LEWISDINIT. LISP] will open the file <LEWIS>INIT.LISP on the host BBN-D 
and make it be the primary input file. The user could then say read[] to obtain the first expression 
on that file. The ftp package extends the functions packfilename, unpackfilename, and 
filenamefield so that they will associate the curly bracket syntax with the new file field HOST. 
Thus, packfilename[HOST ; BBND ; МАМЕ; INIT] will return {BBND} INIT. | 


. Remote files have certain properties that limit how they may be used: 


(1) randaccessp is NIL for such files, and setfileptr may not be applied to them. This means, for 
example, that functions and variables may not be loaded from such files via loadfns. 


(2) the open bytesize of a remote file may not be changed (e.g. by setfileinfo). This means that 
Interlisp-10 compiled files may not be loaded from remote hosts. 


(3) The remote host may close the connection spontaneously (e.g. because of a timeout if the file is 
not referenced for some length of time, or because of a crash). If this happens, the next attempt at 
reading or writing on the file will generate a FILE DATA ERROR. Note: it is unwise to keep a 
remote file open for long periods of time. 


When the connection for the remote file is first established, a password for the remote 


machine/directory may be required. The user will be asked to supply one via the passwords 


package (page 24.44). Alternatively, if the host name has on its property list the property LOGIN 
with value of the form (name password account), sen the indicated name, password, and account 
will be used to log the user into the remote host.97 


ftp[host; file;access;user;password account; веће] 


Opens а network connection to the ftp server at host. If 


access = INPUT or OUTPUT, ftp works like openfile: value is a a literal 
atom of the form {host}file which can then be used as a file name 
by all Interlisp input and output functions, e.g. read, print, 
copybytes, е{с.58 |... For | example, 


65 Note: it is fairly expensive to open a network connection as compared with the time to open a local file, e.g. an 
order of magnitude slower. 

66 For input files, these limitations may be skirted conveniently in the following way: if a colon appears between the 
last character of the host name and the right curly bracket (e.g. (BBND: }<LEWIS>INIT.LISP), then the remote 
file will be copied to a temporary local file when it is opened, and all subsequent references will be to that local file. 

67 If the value is of the form (name NIL account), then getpassword[name] will be used for the password. If the 
account ficld is NIL, no account will be supllied to the remote host. If no LOGIN property is supplied, ANONYMOUS 
will be used as the user name. 

68 


In rcality, this "file" is a network connection to the host's Пр server. This "file" has а whenclose attribute (Section 
14) associated with it so that when Intcrlisp closes the file, the correct terminating scquence will be performed. 
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ftp[SU-AI YUMYUMZ[P,DOC%] INPUT] will allow the Stanford | 
Restraurant .Guide to be read. Note that file must satisfy the Ше 
name conventions of the remote host. 


If access=DIRECTORY, then ар. will print оп the terminal the 
names of all files which match file, e.g. 
ftp[PARC-MAXC2 <NETLISP>*.SAV DIRECTORY]. 


user, password, and account are used for logging in to the remote - 
host. If not supplied, the values are obtained from the LOGIN 
property (if any) as described above. bytesize is the byte size in 
which to open the connection. bytesizes of 7, 8, 16, 32 апа 36 аге 
supported. bytesize=NIL defaults to 7. | 


24.18 МЕТ“ 


This package contains functions for establishing ARPANET connections from an Interlisp-10 job. 
A connection is described by and is an instance of the record CONNECTION. The only fields of 
interest to the user in this record are IN and OUT, which are guaranteed to be car and cadr, 
respectively. IN is a file name which can be read from, OUT a file name which can be printed to. 


makenewconnection[host;type;skt;scratchconn; waitflg] 
makes a connection to host. For t type = А РА, host is the name of 
the host to which the connection is to be made.” For skt=NIL 
(the normal case), the connection will be to the telnet server of 
host; connections to other servers can be made by pew as the 
appropriate value for skt. | 


The value of makenewconnection is a connection. If waitflg is 
non-NIL, makenewconnection waits until its request for connection 
is acknowledged. Otherwise, checkconnection must be called on the 
result before it is used (this allows additional processing to be done 
while waiting for the remote host to respond). 


If scratchconn is non-NIL, it is a scratch connection which is 
reused. | 


For example, (MAKENEWCONNEC TION | BEND) makes an ARPA connection to BBND, 
cen '50-АТ 'ARPA 'FINGER) makes a connection to the Stanford whereis 
service. 


closeconnection[connection] Closes the given connection and replaces the IN and OUT fields 
with NIL. 


The net package was written by L. M. Masinter. It is contained on the file МЕТ СОМ, 


70 Other valucs of type are supplicd when makenewconnection is called from arpauser or arpaserver, described below. 
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checkconnection[connection] | Checks to make sure that Ше given connection is still open (e.g. it 
hasn’t been closed remotely). If the connection is valid, conncction 
is returned. If the connection is in an in-between state, i.e. in Ше 
process of being opened or closed, checkconnection waits to see 


what happens before returning. Otherwise the connection is cleaned . 


up (as if a closeconnection were performed) and checkconnection 
returns NIL. 


netserver[arpa # ;waitflg] Initiates a "server" connection. This is a connection which will talk · 
to a "user" connection. If waitflg is non-NIL, waits for a user to. 


connect; if waitflg — NIL, returns immediately (and checkconnection 
must be called on the connection before the connection is actually 
used). arpaZ defaults to 0. | 


netuser[host;user;arpa # ; waitflg] | 
Initiates the other half of an arpa connection. arpa# defaults to 0 
and must be the same as the argument given the corresponding call 
to netserver. user must be the USERNUMBER (directory number) 
under which the server job is logged in. 


For example, to establish an ARPANET connection between two Interlisp jobs (which can then be 
written to and read from like files), do (SETQ CONN (NETSERVER) ) in one job and 
(SETQ CONN (NETUSER HOST USER) ) in the other job, where host is the machine on which 


the first job is running and user is the directory number under which the first job is logged іп 


(obtainable through the function usernumber). Then, perform (CHECKCONNECTION CONN) in 
each job; when these return, the connection is ready to be used. 


forceout{connection/ file] Normally, characters sent to the "OUT" of a connection are 
| buffered locally. The function forceout can be used to force 
partially filled packets of bytes to be sent across the connection. 
The argument to forceout can either be the connection record or 
the OUT filename. 


24.19 HASH -- A HASH-CODED DICTIONARY FACILITY”! 

The hash package is an Interlisp-10 facility that permits information associated with string or atom 
"keys" to be stored on and retrieved from files. The information (or "values") associated with the 
keys in a file may be numbers, strings, or arbitary s-expressions. The associations are maintained 


key. 


A Бази е may contain information other than key-value associations. The user may print on the 
file using ordinary printing functions (c.g. prinl, printdef), and he may also store non-character 


71 
van Melle. It is contained on the file HASH. COM. 
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by a hashing scheme that minimizes the number of page-maps it takes to access a value from its 


The hash package, implemented by R. Kaplan, is an extension of previous versions written by L. Masinter and W. · 
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information (e.g. binary data) formatted to suit his particular applications. This information is 


stored in regions of the file distinct from the hash index. The hash index can be used to locate 


non-hash information, if ше necessary Ше addresses аге stored as hash values. 


A hashfile is created by the function createhashfile: 


openhashfile[file;access] 
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createhashfileffile; ае Шетелден; # entries] 


A new version of file is opened and initialized as а hashfile. 
valuetype is one of NUMBER, STRING, EXPR, УРАН ог 
SYMBOLTABLE, ‘interpreted as follows: | | 


NUMBER . The values are 24-bit unsigned integers. 


STRING ‘The values are strings with less than 128 
characters. | | (7 И 
EXPR The values are arbitrary s-expressions’2, | 


SMALLEXPR The values аге arbitrary s-expressions such that 
(NCHARS value T HASHFILERDTBL) is less than 128. Storing 
and retrieving is more efficient than for the more general EXPR 
valuetyp. 

SYMBOLTABLE Тһе values are 24-bit unsigned numbers, as for 
valuetype NUMBER, except that the numbers are treated as the 
addresses of "symbols" located. on non-hash pages in the file. бее 
the discussion of symbol-tables below. | 


The other arguments to createhashfile are optional. itemlength is 
the user's estimate of the average number of characters in Ше 


entries he expects to store in the hashfile (= the average key length 
plus the average number of characters in the values for valuetype _ 
STRING ог SMALLEXPR). # entries is an estimate of the the total | 

number of key-value associations he is likely to store. These two 
arguments determine how many pages in the file will be initially 


allocated as hash-pages; accurate estimates can reduce the number 


of times that the file must be rehashed as information is stored in 
it. If these arguments are not к reasonable defaults аге 
supplied. | 


After being initialized, Ме is left open and createhashfile returns as _ 
its value a hashfile datum, a handle on the hashfile that may be 
used as an argument for most of the functions described below. 


Re-opens the previously existing hashfile file. access may be 
INPUT (or NIL), in which case file is opened for reading only, or 
BOTH, in which case file is open for both input and output. Causes 
an error NOT A HASHFILE, if file is not recognized as a hashfile. 


If access is BOTH and file is a hashfile open for reading only, 


The values are stored by printing them in the file with hashfilerdtbl, initially ORIG. 
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hashfilep[x] 


The following functions require an open hashfile as an ^ argument, i.e. an object f for which hashfilep | 


is non-NIL. 


puthashfile and gethashfile are the basic functions for storing and retrieving values in an open 


hashfile: 


HASH -- A Hash-Coded Dictionary Facility 


openhashfile attempts to close it and re-open it for writing. 
Otherwise, if file designates an already open hashfile, openhashfile 
is a no-op. 


The value of openhashfile is a hashfile datum. 


Returns x if x is a hashfile datum (ie, a value returned by 


createhashfile or openhashfile). If x is NIL, returns syshashfile if it © 
is а hashfile datum. If x is the name of an open hashfile, returns 


the corresponding hashfile datum. Otherwise, returns NI IE 


puthashfile[key;value;hashfile] Puts value in hashfile, indexed under key. If value is NIL, any 


gethashfile[key;hashfile] 


hashfileprop[hashfile;prop] 


hashfilename[hashfile] 


closchashfile[hashfile] 


previous entry for key is deleted. 


Returns the value corresponding to key in hashfile. For files of 


valuetype STRING, NUMBER, or SYMBOLTABLE, the value 
returned by gethashfile is temporary in that any subsequent calls (0 _ 


hash or pmap function may smash it. concat or mkatom must be 
applied if the value is a string, or iplus if it is a number, in order to 
make the value permanent. 


returns the value of the prop property of hashfile. The recognized 

props s and the values returned are: | 

VALUETYPE one of NUMBER, STRING, etc. 

NAME | . the full name of the file. 

ACCESS BOTH if file is open for writing, INPUT if it 1s 
read-only. 


same as hashfileprop[hashfile; NAME]. | 


same as closcffhashfileprop[hashfile;NAME]]. 


The function hashstatus can be used as a STATUS function for Ше whenclose package (Section 14) 


to restore the state of a hashfile when a sysout is resumed. If hashstatus is used, the permstatus | 


package (page 24.34) must also be loaded. 


The functions in the following group opcrate on all the keys in a hashfile: | 
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maphashfile[hashfile;mapfn] | 
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For each entry . in hashfile, performs 
mapfn[key;gethashfile[key;hashfile]. If mapfn is a function of only 


one argument, performs mapfn[key] thereby о the call to с 


gethashfile needed to obtain the value. key (also value for 
STRING, NUMBER, and SYMBOLTABLE files) is temporary, as for 


ecthashfile. 


After many insertions and deletions much of the space in a hashfile 
may be unusable. rehashfile reclaims that space by rehashing all 


the keys. The information on non-hash pages in the file is not 
altered or moved (except that the pname-pointers in а 
SYMBOLTABLE file are eee See below.). 


оорума newname;fn; уре]. 


calls createhashfile to open | newname as a hashfile, with valuetybe: 
itemlength and #entries determined by examining the open 
hashfile hashfile. Then maps through all the keys in hashfile, ша: 
the equivalent valent of: 


puthashfilefkcy gethashfile{key:hashfile]:newhashfile] 


for each key. In essence, copyhashfile copies the hash potum of | 
hashfile to newname. 


If fn is given, then it is applied to the successive bd of hashfile, 
the old hashfile, and the new hashfile, and the value returned is 
used as the value in the new Ме. In effect, 


 puthashfile[kcy; fn[gethashfile[kcy ;hashfile]:hashfile;newhashfile]; newhashfile] | 


is evaluated for each key. Thus, the user can intervene as each key 
is processed in order to copy information associated with the key 
that resides on non-hash pages. | 


For example, ап EXPR file could be implemented by Ини the 
full s-expressions in a NUMBER file’s printing region (see below) and 
storing their byte-positions as hash values. Instead of reading an 
s-expression into internal data structures before writing it out to the 
new file, a fn could be given that transferred Ше s-expression to the 
new file more efficiently, via copybytes. The function would return 
the byte-position on the new file where the expression. ended up. 73, 


If fn is given, then уіуре, if specified, is a temporary valuetype 


(NUMBER, STRING, etc.) to be used during copying. This permits 
the user to force the valuetype of both files to one more suited for 
fn, eg. SMALLEXPR to STRING ог EXPR to NUMBER, as in the 


example. vtype does not affect the permanent тше of either — 


file. 


Actually, this is the way EXPR files are copied if fn is not specified 
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hashfilesplst[hashfile] Returns a "generator" for the keys in hashfile that is acceptable as 
"а an argument to fixspell. Thus, (FIXSPELL BADWORD 70 


(HASHFI LESPLST hashfile)) will spelling correct a word using the 


keys in hashfile. 


lookuphashflefkey valuc;hashfile; -calltype} 
a generalized entry for inserting and retrieving values; provides 
certain options not available with gethashfile or puthashfile. 


calltype is one of RETRIEVE, DELETE, REPLACE, INSERT ora 
list of any combination of them. lookuphashfile looks up key in 


hashfile. If key is found, then if calltype is or contains RETRIEVE, 
the old value is returned from lookuphashfile; otherwise returns T. 
If calltype is or contains DELETE, the value associated with key is 
deleted from the file. If calltype is or contains REPLACE, the old 
value is replaced with value. 


If key is not found, returns NI L. In addition, if calltype i is or 


contains INSERT, lookuphashfile inserts value as the value 


associated with key. 
Examples: 


To either return an old value or insert a new value in the file if one does not already exist, 


perform lookuphashfile[key;newvalue;hashfile(INSERT RETRIEVE). The value returned will be 


NIL if newvalue was inserted, or the old value if key was found. 


To merely check whether key exists in the file without actually retrieving я value (which may бе 


expensive for the more general valuetypes), perform lookuphashfile[key;NIL;hashfile;NIL] 
The function puthashfile is defined as: 


(LAMBDA (KEY VALUE HASHFILE) 
(if VALUE=NIL 
then (LOOKUPHASHFILE KEY NIL HASHFILE DELETE) 
else (LOOKUPHASHFILE KEY VALUE HASHFILE '(INSERT REPLACE 
VALUE] | 


And gcthashfile is defined as: 


(LAMBDA (KEY HASHFILE) (LOOKUPHASHFILE KEY NIL HASHFILE 'RETRIEVE]) 


UNSTRUCTURED PAGES AND SYMBOL TABLES 


The non-hash information in a hash-file may be formatted as printed character strings or binary 
data. Printed information resides in a file's "printing region", while binary data is stored on 
"unstructurcd pages". 


Unstructured pages іп a file are allocated and dcallocated by the hash package so that they do not 


encroach on hash or printing pages. Other than that, the user has complete freedom to map them 
in via mapin or locate for arbitrary reading and writing. The primitive opcrations аге: 
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getpage[hashfile;n] | | returns the page number of a free page in hashfile. If n is given, 
| И then the user is guaranteed that the page returned is the first of n 
contiguous pages all of which are free. 


delpage[page # ;hashfile] removes page page# from hashfile. page# should be the number 
of an unstructured page, either a value of getpage or within the 
block of free pages guaranteed by getpage. The contents of the 
page in the file are lost, and the page itsclf becomes available for 
re-allocation either by getpage or internally as a hash page. If 
page# happens to be the number of a hash page, the hashing 
information will be destroyed. 


Unstructured pages are available on hashfiles so that the user can link hash keys to data in special 
formats. For example, the user might associate lists of properties with a key by writing the 
properties on an unstructured page, and then storing the file address of the properties as the value 
of the key in a NUMBER file. The properties could be retrieved by applying locate to 


 gethashfile[key;hashfile]. 


A SYMBOLTABLE hashfile provides an additional feature that makes it possible to implement 
arbitrary file-resident symbol processing systems. The user may store the data to be associated. 
with a key on unstructured pages, and he can then link the file address to the key via puthashfile, 
as described above. The difference between a NUMBER and SYMBOLTABLE file is that for a 
SYMBOLTABLE, the hash package also stores the reverse link from the file address to the key. This 
makes it possible to obtain a "print-name" for an address on an unstructured page, via the function 
getpname: | | : PL 


getpname[fileadr;hashfile] returns a temporary string containing the characters of the key 


whose hash value is the 24-bit unsigned fileadr. Causes an error if- 
hashfile is not a SYMBOLTABLE file. 


The hash package automatically updates the print-name information for the file address if the key 
is relocated by rehashing, and it destroys the back-link if the value for the key is deleted. A 
SYMBOLTABLE file imposes one restriction on the way unstructured pages are treated: If a file 
address is stored as a hash-value for some key, then the right-most 24 bits of the word at that 
location in the file are reserved for the use of the hash mechanism. М The user must not write into 
it. 


With these primitives, a list-processing system with a 24-bit non-resident address space is easy to 
build. The user is responsible for allocating "atoms" on unstructured pages, and updating the 
"atom hash table" with puthashfile. The second (and subsequent) words after an atom address 
may be used to store the atom’s "property list", containing other atom addresses, or other addresses 
interpreted as pointers to "cons" cells. These can also be allocated on unstructured pages. It is a 
simple matter to implement the equivalent of car, cdr, rplaca, and rplacd. | 


74 The left-most 12 bits are available and can be used for a number of applications, e.g. to store type-bits. 
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HASH -- А Hash-Coded Dictionary Facility 


THE PRINTING REGION 


Hashfiles are organized so that it is always permissible to print at the end of the file with ordinary 
Interlisp output functions. That is, the file is arranged so that the hash and unstructured pages are 
always located before the end-of-file for sequential reading and writing. This is accomplished by 
creating the file with the end-of-file some number of free pages past the last hash or unstructured 
page. When all free pages below the end-of-file have been used, the end- of file 15 moved 50 that 
there are again a reservoir of free pages before it. 


Thus, the motis region may shift as a result of calls to getpage or puthashfile, and the user 
cannot rely on the output from two different printing operations being located at adjacent positions 
in the file. The expressions he prints cannot be retrieved by successive calls to standard reading 
functions. Instead, the user should record the byte position of each printed expression as a hash 


· value or on an unstructured page so that he may use setfileptr to position the file properly. If he- 


does change the file's byte-pointer, he must be sure to reset it to the end-of-file (e.g. 
sctfileptr[file; -1]) before more printing is done. | 


24.20 THE DECL PACKAGE? 


INTRODUCTION 


The Decl package extends Interlisp to allow the user to declare the types of variables and 


expressions appearing in functions. It provides a convenient way of constraining the behavior of 
programs when the generality ша flexibility of ordinary Interlisp is either unnecessary, confusing, 
or inefficient. | 


The Decl package provides а simple language for declarations, and augments the interpreter апа 
the compiler to guarantee that these declarations are always satisfied. The declarations make 
programs more readable by indicating the type, and therefore something about the intended usage, 
of variables and expressions in the code. They facilitate debugging by localizing errors that 
manifest themselves as type incompatibilities. Finally, the declaration information is available for 
other purposes: compiler macros can consult the declarations to produce more efficient code; 
coercions for arguments at user interfaces can be automatically к and the declarations will 
be noticed by the Masterscope function analyzer. 


The declarations interpreted by the Decl package are in terms of a set of declaration types called 
decltypes, each of which specifies a set of acceptable values and also (optionally) other type specific 
behavior. The Decl package provides a set of facilities for defining decltypes and their relations to 
each other, including type valued expressions and a comprehensive treatment of union types. 


The following description of the Decl package is divided into three parts. First, the syntactic 
extensions which permit the concise attachment of declarations to program elements are discussed. 
Second, the mechanisms by which new decltypes can be defined and manipulated are covered. 
Finally, some additional capabilities based on the availability of declarations are outlined. 
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Teitelman and Г. M. Masinter. It is contained on the file DECL.COM. The Decl package requires the LAMBDATRAN 
package, which will automatically be loaded with Decl if it is not already present. 
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The Decl package was designed and implemented by R. M. Kaplan and B. A. Sheil, with the assistance of №. 
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USING DECLARATIONS IN PROGRAMS 


Declarations may be attached to the values of arbitrary expressions and to LAMBDA and prog 
variables throughout (or for part of) their lexical scope. The declarations are attached using 


constructs that resemble the ordinary Interlisp LAMBDA, prog, and progn, but which also permit the 


expression of declarations. The following examples illustrate the use of declarations in programs. 
Consider the factorial function discussed in Section 2: 


[LAMBDA (N) 
( COND 
((EQ N 0) 1 
(Т (ITIMES N (FACT (5081 N] 


Obviously, this function presupposes that n is a number, and the run-time checks in itimes and 
subl will cause an error if this is not so. For instance, F ACT(T) will cause an error and prin print the 
message NON-NUMERIC ARG T. By defining FACT as a DLAMBDA, the Decl package analog of 
LAMBDA, this presupposition can be stated directly in the code: 


[DLAMBDA ((N NUMBERP)) 
(COND 
((Е0 М 0) 1) 
(Т (ITIMES N (FACT (5081 N] 


With this definition, FACT(T) will not result in a NON- NUMERIC ARG T error when the body of 


the code is executed. Instead, the numberp declaration will be checked when the function is first | 
entered, and a declaration fault will occur. Thus, the message that the user will see will not dwell 
on the offending value T, but instead give a symbolic indication of what variable and declaration 
were violated, as follows: _ E 


DECLARATION NOT SATISFIED | 
Hee BROKEN) 


The user is left in a break from which the values of variables, e.g. n, can be examined to determine 
what the problem is. 


The function fact also makes other presuppositions concerning its argument, n. For example, fact 
wil go into an infinite recursive loop if n is a number less than zero. Although the user could 
program an explicit check for this unexpected situation, such coding is tedious and tends to 
obscure the underlying algorithm. Instead, the requirement that n not be negative can be 
succinctly stated by declaring it to be a subiype of NUMBERP which is restricted to non-negative 
numbers. This can be done by adding a SATISFIES clause to n’s type specification: 


[DLAMBDA ([М NUMBERP (SATISFIES (NOT (MINUSP М1) 
(COND 


((ЕО М 0) 1) 
( 


( 
Т (ІТІМЕ5 М (РАСТ (5081 М1 


"The predicate іп the SATISFIES clause will be evaluated after n is bound and found to satisfy 


numberp, but before the function body is executed. In the event of a declaration fault, Ше 
SATISFIES condition will be included in the error message. For cxample, FACT(-1) would result 
in: | | 


DECLARATION МОТ SATISFIED 
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((N NUMBERP (SATISFIES (NOT (MINUSP N))) BROKEN) | 


The DLAMBDA construct also permits the type of the value that is returned by the function to be 
declared by means of the pseudo-variable RETURNS. For example, the following definition 
specifies that fact is to return a positive integer: 


[DLAMBDA ([N NUMBERP (SATISFIES (NOT (MINUSP N] 
[RETURNS FIXP (SATISFIES (IGREATERP VALUE 0]) 
(COND 
((EQ N 0) 1 
(T (ITIMES N (FACT (зив1 N] 


After the function body is evaluated, its value is bound to the variable value and | {һе RETURNS 
declaration is checked. A declaration fault will occur if the value is not satisfactory. This prevents 


a bad value from propagating to the caller of fact, perhaps causuig an error far away from the 


source of the difficulty. 


Declaring a variable causes its value to be checked not only when it is first bound, but also 
whenever that variable is reset by setq within the DLAMBDA. In other words, the type checking 
machinery will not allow a declared variable to take on an improper value. An iterative version of 
the factorial function illustrates this feature in the context of a dprog, the Decl package analog of 
prog: 


(DLAMBDA ([N NUMBERP (SATISFIES (NOT (MINUSP К] 
[RETURNS FIXP (SATISFIES (IGREATERP VALUE 01) 
[DPROG (ГТЕМР 1 ҒІХР (SATISFIES (IGREATERP TEMP 01. 
[RETURNS FIXP (SATISFIES (IGREATERP VALUE 01) 
LP (COND ((EQ N 0) (RETURN ТЕМР))). 

(SETQ TEMP (ITIMES N TEMP)) 

(5ЕТ0 М (SUB1 N)) 

(GO LP] 


dprog declarations are much like DLAMBDA declarations, except that they also allow an initial value 


for the variable to be specified. In the above example, temp is declared to be a positive integer 
throughout the computation and n is declared to be non-negative. Thus, a bug which caused an 


incorrect value to be assigned by one of the s setq expressions would cause a declaration failure. 
Note that the RETURNS declaration for a dprog is also useful in detecting the common bug of 
ыы; an explicit RETURN. 


DLAMBDAS 


The Decl package version of a LAMBDA expression. is an expression beginning with the atom _ 


DLAMBDA. Such an expression is a function object that may be used in any context where а 
LAMBDA expression may be used. It resembles a LAMBDA expression except that it permits 
declaration expressions in its argument list, as illustrated in the examples given earlier. Each 
clement of the argument list of a DLAMBDA may be a litcral atom (as in a conventional LAMBDA) 
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or a list of the form (name type . extras)./6 


name fulfills the standard function of a parameter, i.e. providing a name to which the value ofthe 


| corresponding argument will be bound. 


type is either a Decl package type name or type expression. When the DLAMBDA is entered, its 
arguments will be evaluated and bound to the corresponding argument names, and then, after all 
the argument names have been bound, the declarations will be checked. The type checking is 
delayed so that SATISFIES predicates can include references to other variables bound by the 
same DLAMBDA. For example, one might wish to define a function whose two arguments are not 
only both required to be of some given type, but are also required to satisfy some кы; | 
(e.g., that one is less than Ше other). | | 


ех tras allows some additional properties to be attached to a variable. One such property is the | 
accessibility of name outside the current lexical scope. Accessibility specifications include the atoms 
LOCAL or SPECIAL, which indicate that this variable is to be compiled so that it is either a 

localvar or a specvar, respectively. This is illustrated by the following example: — | | 


[DLAMBDA ((A LISTP SPECIAL) 
(В FIXP LOCAL)) 


i] 


A more informative equivalent to the SPEC IAL key word is the USEDI N form, the tail of which | 
can be a list of the other functions which are expected to have access to the variable: 27 


[DLANBDA ((A LISTP (USEDIN FOO FIE)) 
(B FIXP LOCAL)) 


„1 


extras may also ТАР а comment іп andad format, so that descriptive information may be 
given where a variable is bound: | 


[DLAMBDA ((А LISTP (USEDIN FOO ЕТЕ)  (* This is ап important variable)) 
|. (B ҒІХР LOCAL)) | | | 


„1 


As mentioned earlier, the value returned бу а 01 АМВРА сап also be declared, by means of the 
pseudo-variable RETURNS. The RETURNS declaration is just like other DLAMBDA declarations, 
except (1) in any SATISFIES predicate, the value of the function is referred to by the 
distinguished name value; and (2) it makes no sense to declare the return value to be LOCAL or 
SPEC IAL. | | 


76 Strictly, this would require а declaration with а SATISFIES clause to take the form 
(М (NUMBERP (SATISFIES --)) --) (page 24.62. However, due to the frequency with which this 
construction is used, it may be written without the inner set of parentheses, eg. 
(М NUMBERP (SATISFIES --) --). | 


USEDIN is mainly for documentation purposes, since there is no way for such a restriction to be enforced. 
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DPROGS 


Just as DLAMBDA resembles LAMBDA, dprog is analogous to prog. As for an ordinary prog, a 
variable binding may be specified as an atom or a list including an initial value form. However, a 
dprog binding also allows type and extras information to appear following the initial value form. 
Тһе format for these augmented variable bindings is (name initialvalue type . extras). Note that 


the only difference between a dprog binding and a DLAMBDA binding is that the second position is - 


interpreted as the initial value for the variable./? The same rules apply for the interpretation of the 
type information for dprogs as for DLAMBDAs, and the same set of optional extras can be used. 


dprogs may also declare the type of the value На return, by Specifying the шон апаЫе 


J— RETURNS. 


Just as for a DLAMBDA, type tests in a dprog are not asserted until after all the БЕ have been 

bound, thus permitting predicates to refer to other variables being bound by this dprog. If NIL 
appears as the initial value for a binding (ie. the atom NIL actually appears in the code, not 

simply an expression which evaluates to NIL) the initial type test will be suppressed, but 
subsequent type tests, c.g. following а setq, will still be performed. 


A common construct in Lisp is to bind and initialize a prog variable to the ж of a complicated 
expression in order to avoid recomputing it and then to use this value in initializing other prog 
| variables, e.g. | 
[PROG ((A expression)) 0 ма Тоа 
| SRETURN (PROG ((B (= А ..)) (С (... А ..))) 


The ugliness of such constructions in spavedtanal: Lisp often tempts the programmer to loosen the 


scoping relationships of the variables by binding them all at a single level and using setq’s in the 


body of the prog to establish the initial values for апае that depend on the initial values of 
other variables, e.g. | 


[PROG ((А expression) B С). 
(ФЕТО B („А ..)) 
(ФЕТО С (.. А ..)) 
1 | 


In the Decl package environment, this procedure undermines the protection offered by the type 
mechanism by encouraging the use of uninitialized variables. Therefore, the dprog offers a syntactic 
form to encourage more virtuous initialization of its variables. A dprog variable list may be 
segmented by occurrences of the special atom THEN, which causes the binding of its variables in 
stages, so that the bindings made in earlier stages can be used in later ones, e.g. 


[DPROG ((A (LENGTH FOO) FIXP LOCAL) 


THEN (В (SQRT A) FLOATP) 
THEN (C (CONS A B) LISTP)) 
1 


. Each stage is carried out as a conventional set of dprog bindings (i.c., simultancously, followed by 


the appropriate type testing). This layering of the bindings permits onc to gradually descend into a | 


78 Thus, if the user wishes to supply a type declaration for a variable, an initial value must be specified. 
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inner scope, binding the local names in a very structured and clean fashion, with initial values 
type-checked as soon as possible. | 


DECLARATIONS IN ITERATIVE STATEMENTS 


The clisp iterative statement (Section 23) provides a very useful facility for specifying a variety of 
progs that follow certain widely used formats. The Decl package allows declarations to be made 
for the scope of an iterative statement via the declare clisp is.opr. declare can appear as ап 
operator anywhere in an iterative statement, followed by a list of declarations, for example: 


(for J from 1 to 10 declare (J FIXP) do =). | 


. Note that declare declarations 45 not create bindings, but mercly оре equ ай for existing 


bindings. For “ог this reason, an initial value cannot be specified and the form of the declaration is the 
same as that of DLAMBDAs, namely (name type . extras). 


DECLARING A VARIABLE FOR A RESTRICTED LEXICAL SCOPE 


The Decl package also permits declaring the type of a variable over some restricted portion of its 
existence. For example, suppose the variable x is either a fixed or floating number, and a program 
branches to treat the two cases separately. On one path x is known to be fixed, whereas on the 
other it is known to be floating. The Decl package dprogn construct can be used in such cases to 
state the type of the variable along each path. dprogn is exactly like progn, except that the second 
element of the form is interpreted as a list of DLAMBDA format declarations. These declarations are 
added to any existing declarations in the containing scope, and the composite declaration? is 
considered to hold throughout the lexical Scope created by the dprogn. Thus, our example 
becomes: | | 


(if (FIXP X) then (DPROGN ((X ЕТХР)) .. stuff...) - 
else (DPROGN ((X FLOATP)) ... otherstuff ...) ) 


Like dprog and DLAMBDA, the value of a dprogn may also be declared, using the pseudo-variable 
RETURNS. 


dprogn may be used not only to restrict the declarations of local variables, but also to declare 
variables which are being used freely. For example, if the variable a is used freely inside a 
function but is known to be fixp, this fact could be noted by enclosing the body of the function in 
(DPROGN ((A ЕТХР FREE)) .. body ..) Instead of FREE, the more specific construction 


but also gives the names of the functions which might have provided this binding? 


79 Note that variables bound outside of the scope of the iterative statement, ie. a variable used freely in the i.s, can also 
· be declared using this construction. Such a declaration will only be in effect for the scope of the iterative statement. 

80 created using the ALLOF type expression, page 24.62. 

81 


Like USEDIN declarations, FREE and BOUNDIN dcclarations cannot be checked, and are provided for documentation 
purposcs only. | 
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. (BOUNDIN function, function .. 2) сап be used. This not only states that the variable is used freely 
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Since the dprogn form introduces another level of parenthesization, which results in the enclosed 
forms being prettyprinted indented, the Decl package also permits such declarations to be attached 
to their enclosing DLAMBDA or dprog scopes by placing a DECL expression, eg. 
(DECL (A FIXP (BOUNDIN FUM)), before the first executable form in that СЕ Like 
dprogn's, DECL declarations use DLAMBDA format. и | | м 


DECLARING 1 ТНЕ VALUES OF EXPRESSIONS 


The Decl — allows the value of an ai ~ (о ђе declared with the Ded construct: 


THE. A THE expression is of the form (THE type . forms), ер. (THE FIXP (FOO X)). forms 
are evaluated in order, and the value of the аз! опе is checked to see if it satisfies t type, a type 
name or type иа ло и 50, its Value is retumed, otherwise a declaration fault occurs. 


ASSERTIONS 


The Decl package also allows for PERCENT that an arbitrary predicate holds at a Бо point in 
a program’s execution, e.g. a condition that must hold at function entry but not throughout its 
execution. Such predicates can һе checked using ап expression of the form 


(ASSERT form, form, ... ), in which each form; is either a list (which will be evaluated) ога 
variable (whose declatation will be checked). С Unless all elements of the ASSERT form are satisfied, 


a declaration fault will take place. 


ASSERTing a variable provides a convenient way of Е verifying that the value of the variable has not 


been improperly changed by a lower function. Although a similar effect could be achieved for 
predicates by explicit checks of the form (OR predicate (SHOULDNT ) ), ASSERT also provides the 


ability both to check that а variable’s declaration is currently satisfied and to remove its checks at 
compile time without source code modification (see page 24.60). | 


USING TYPE EXPRESSIONS AS PREDICATES 


The Decl package де {һе Кесога раскаре ТҮРЕ? construct (Section 23) so that it accepts 
decltypes, wel | as record names, eg. 
(TYPE? (FIXP (SATISFIES (ILESSP VALUE. 0))) expr) Thus, a TYPE? expression is 
exactly the same as a THE expression except that, rather than causing a declaration fault, TARET is 
a predicate which determines whether or not the value satisfies the given type. 


ENFORCEMENT 


The Decl package is a "soft" typing system - that is, the data objects themselves are not inherently 
typed. Consequently, declarations сап only be enforced within the lexical scope in which the 
declaration takes place, and then only in certain contexts. In general, changes to a variable's value 
such as those resulting from side effects to embedded structure (ер. rplaca, setn, etc.) or free 
variable references from outside the scope of Ше declaration cannot be, and therefore are not, 
enforced. 


Declarations are enforced i.e. checked, in three different situations: when a declared variable 15. 


bound to some value or rebound with setq or setqq. when a declared expression is evaluated, and 
when an ASSERT expression is evaluated. In a binding context, the type check takes place after 


the binding, including any user-defined behavior specified by the type's binding function. Any 
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failure of the declarations causes a break to occur and an informative message to be printed. In 
that break, the name to which the declaration is attached (or value if no name is available) will be 


bound to the offending value. Thus, in the FACT(T) example on page 24.54, n would be bound to 
T. The problem can be repaired either by returning an acceptable value from the break via the 
RETURN command, or by assigning an acceptable value to the offending name and returning from 
the break via an OK or GO command. The unsatisfied declaration will be reasserted when the - 
computation is continued, so an unacceptable value will be detected.82 


The automatic enforcement of type declarations is a very flexible and powerful aid to program 
development. It does, however, exact a considerable run-time cost because of all the checking 
involved.®? As a result, it is usually desirable to remove the declaration enforcement code when the - 
system is believed to be bug-free and performance becomes more central. Setting the value of the | 
variable compileignoredecl to T (initially NIL) instructs the compiler not to insert declaration | 
enforcement tests in the compiled code. More selective removal can be achieved by setting 
compileignoredecl to a list of function names. Any function whose name is found on this list 15 
compiled without declaration enforcement. Finally, declaration enforcement may be suppressed 
selectively by file using Ше IGNOREDECL file package command. If this appears in а Ме file 
commands, it redefines the value of compileignoredecl to cdr of the IGNOREDECL command for 
the compilation of this file only. 


DECLTYPES 


A Decl package type, or decltype, specifies a subset of data values to which values of this type аге 
restricted. For example, a "positive number" type might be defined to include only those values | 
that are numbers and greater than zero. A type may also specify how certain operations, such as | 
assignment ог binding (see page 24.64), are to be performed on variables declared to be of this 


(уре. | 


The inclusion relations among the sets of values which satisfy the different types define a natural 
partial ordering on types, bound by the universal type ANY (which all values satisfy) and the empty 


_ type NONE (which no value satisfies). Each type has one or more supertypes (each type has at least | 


ANY as а supertype) and one or more subtypes (each type has at least NONE as а subtype). This - 
structure is important to the user of Decl as it provides the framework in which new types are | 
defined. Typically, much of the definition of a new type is defaulted, rather than specified | 


explicitly. The definition will be completes by inheriting atttributes which are shared by all its 


immediate supertypes. 


An initial set of decltypes which defines the Interlisp built-in datatypes and a few other commonly | 
used types is provided. Thereafter, new decltypes are created in terms of existing ones using the . 
type expressions described below. For conciseness, such new types can be associated with literal 


atoms using the function decltype (page 24.63). 


With this exception, assignments to variables from within the break are not considered to be in the scope of the 
· declarations that were in effect when the break took place, and so are not checked. | 


83 Factors of two to ten in running 0600 аге пої ипсоттоп, especially where low level, пешеш а usd. йын 


employ type declarations. 
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PREDEFINED TYPES 


Some commonly used types, such as the Interlisp built-in data types, are already defined when the . 
Decl package is loaded. These types, indented to show subtype-supertype relations, are: 


ANY | m 
ARRAYP ATOM FUNCTION 1578 STACKP STRINGP 
НАВВАҮР | ТТАТОМ | ALIST mE 
READTABLEP _ NIL LISTP 
NUMBERP | 
ЕТХР 
LARGEP 
SMALLP 
FLOATP 


NONE 


+ +++++++++ 


Note that the definition of LST causes NIL to have multiple supertypes, ie. LITATOM and LST, 
reflecting the duality of NIL as an atom and a (degenerate) list. 


In addition, declarations made using the Record package (Section 23) also define types which are 
attached as subtypes to an appropriate existing type (e.g, a typerecord declaration defines a. 
subtype of LISTP, a datatype declaration a Subtype of ANY, etc.) and may be used directly in 


++ 


declaration contexts. 


TYPE EXPRESSIONS 


Type expressions provide convenient ways for defining new types in terms of modifications to, or 
compositions of one or more, existing types. 


(MEMQ value, ... 


(ONEOF type, ... type,) 


84 


85 


LST is defined as сег LISTP or NIL, i.e. a list or NIL. The name LST is used, because the name LIST is treated · 


specially by clisp. 


valuen) 


specifies a type whose values can be any one of the fixed set of 
elements (value; ... value,}. For example, the status of a device 
might be represented by a datum restricted to the values BUSY and 
FREE. Such a “device status". type could be defined via 
(MEMQ BUSY FREE). The new type will be a subtype of the 
narrowest type which all of the alternatives satisfy (e.g., the "device 
status” type would be a subtype of LITATOM). The membership 
test uses eq if this зирспуре 15 LITATOM; equal otherwise. Thus, 
lists, floating point numbers, etc., can be included in the set of 
alternatives. 


specifies a type which is the union of two or more other types. For 


ALIST is defined as cither NIL, ог а list of elements each of which is of type LISTP. 
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example, the notion of a possibly degenerate list is something that 
is either LISTP or NIL. Such a type can be (and the built in type 
LST in fact is) defined simply as (ONEOF NIL LISTP). A union 
data type becomes a supertype of all of the altcrnative types 
specified in the ONEOF expression, and a subtype of their lowest 
common supertype. The type properties of a union type are taken 
from its alternative types if they all agree, otherwise from the 
supertype. | | 


specifies а type which is the intersection of two or more other | 
types. For example, a variable may be required to satisfy both > 
FIXP and азо some type which і defined а 
(NUMBERP (SATISFIES predicate)). The latter type will admit — 
numbers that are not FIXP, i.e. floating point numbers; the former 
does not include predicate. Doth restrictions can be obtained by 
using the type 

(ALLOF (NUMBERP (SATISFIES predicate)) FIXP).°6 


specifies a type which is an aggregate of values of some other type 
(e.g., list of numbers, array of strings, etc.). aggregate must be a 
type which provides an EVERYFN property (page 24.64). The 
EVERYFN is used to apply an arbitrary function to each of the 
elements of a datum of the aggregate type, and check whether the 


. result is non-NIL for each element. element may be any type 
expression. For example, the type "list of cither strings or atoms" 


can be defined as (LISTP OF (ONEOF STRINGP ATOM)). The 
type test for the new type will consist of applying the type test for 


element to each element of the aggregate type using the EVERYFN 


property. The new type will be a subtype of its aggregate type.” 


.. form,)) 


specifics a type whose values are a subset of the values of an 
existing type. The type test for the new type will first check that 
the base type is satisfied, i.e. that the object is a member of type, 


and then evaluate form n form,. If each form returns a non-NIL 


value, the type is satisfied. 


The value that is being tested may be referred to in form, ... form, 
by either (a) the variable name if the type expression appears in a 
binding context such as DLAMBDA or dprog (b) the distinguished 
atom elt for a SATISFIES clause on the elements of an aggregate 
type, or (c) the distinguished atom value, when the type expression 
is used in a context where no пате is available (с.р., a RETURNS 
declaration). For example, one might declare the program variable 


When a value is tested, the component type tests are applied from left to right. 


+ 87 The built-in aggregate types are arrayp, listp, Ist, and stringp (and thcir subtypes). 
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а ю% Бе а перайуе integer . via 
(FIXP (SATISFIES (MINUSP A))), or declare the value of a 
DLAMBDA to be of type  ((ONEOF FIXP FLOATP) 
(SATISFIES (GREATERP VALUE 25))). Note that more than 
one SATISFIES clauses may appear in a single type expression 
attached to different alternatives in a ONEOF type expression, or 
attached to both the elements and the overall structure of an 
aggregate. For example, 


[LISTP OF [FIXP (SATISFIES (ILEQ ELT MEM 
(SATISFIES (ILESSP (LENGTH VALUE) 7] 


specifies a list of less than 7 integers each of which is no greater 
than the first element of the list. 


(SHARED type) Specifies a subtype of type with default binding behavior, е. the 


binding function (see page 24.64), if any, will be ѕирргеѕѕей. 88 For 


example, if the type FLOATP were redefined so that DLAMBDA and. 


dprog bindings of variables that were declared to be FLOATP 
copied their initial values (e.g., to allow setns to be free of side 
effects), then variables declared (SHARED F LOATP ) would be 
initialized in the normal fashion, without copying their initial 
| values. 


NAMED TYPES 


Although type expressions can be used in any declaration context, it is often desirable to save the 
definition of a new type if it is to be used frequently, or if à more complex specification of its 


behavior is to be given than is convenient in an expression. The ability to define a named type is 


provided by the function decltype. 


decltype[typename;type;prop; ;val; ;...;propq;valy] а 
Крда 2 nospread function. typename is a literal atom, type is 

either the name of an existing type or a type expression, and prop), 

val), ..., prop,, val, is a specification (in property list format) of 

other attributes of the type. decltype derives a type from type, 


associates it with typename, and then defines any properties 


specified with the values given. 


The following properties are interpreted by the Decl package. 89 Each of these Properties can | have 
as its value either a function name or a LAMBDA expression. 


As no predefined type has a binding function, this is of no concern until the user defines or redefines a type to have 
a binding function. 


89 


Actually, any property can be attached to a type, and will be available for use by user functions ма the function 
getdccltypeprop, described below. | 
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TESTFN fn | will be used by the Decl package to test whether a given value 


satisfies this type. The type is considered satisfied if fn applied to 
the item is non-NIL. For example, one might define the type 
INTEGER with TESTFN fixp.” 


EVERYFN fn Е specifies a mapping function which сап apply a functional argument 


to each "element" of an instance of this type, and which will return 
NIL unless the result of every such application was non-NIL. fn 
must be a function of two arguments: the aggregate and the 
function to be applied. For example, the EVERYFN for the built-in 
type LISTP is every. As described on page 24.62, the Decl package. 
uses the EVERYFN property of the aggregate type to construct a 
type test for aggregate type expressions. In fact, it is the presence of 
an EVERYFN property which allows a type to be used as ап. 
aggregate type. | | = 


BINDFN fn | is used to compute from the initial value supplied for а DLAMBDA 


or dprog variable of this type, the value to which the variable will 
actually be initialized. fn must be a function of one argument 
which will be applied to the initial value, and which should 
produce another value which is to be used to make the binding. 
For example, a BINDFN could be used to bind variables of some 
type so that new bindings are copies of the initial value. Thus, if 
FLOATP were given the BINDFN fplus, any variable declared 
FLOATP would be initialized with a new floating box, rather tian, 
sharing with that of the original initial value. 


SETFN fn E а is used for performing a setq ог setqq of variables of this type. fn 


91 


9 


94 


9 


is a function of two arguments, the name of the variable, and its 
new value. A SETFN is typically used to avoid the allocation of 
storage for intermediate results. Note that the SETFN is not the 
mechanism for the enforcement of type compatibility, which is 


— Typically, the TESTFN (ог a type is derived from its type expression, rather than specified explicitly. The ability to 


specify the TESTFN is provided for those cases where a predicate is available that is much more efficient than that 
which would be derived from the type expression. For example, the type SMALLP is defined to have the function 
smallp as its TESTFN, rather than (LAMBDA (DATUM) (AND (NUMBERP DATUM) (ҒІХР DATUM) 
(SMALLP DATUM))) as would be derived from the subtype structure. | | 


Note that а type's EVERYFN is пог used in type tests for that type, but only in type tests for types defined by OF 
expressions (page 24.62) which used this type as the aggregate type. For example, every is not used in determining 
whether some value satisfies the type LISTP. 


The Decl package never applics the EVERYFN of a type to a value without first verifying that the value satisfies that 
type. ! 


For a dprog binding, fn fn will be applied to no arguments if the initial value is lexically NIL, 


The BINDF н, if any, associated with а type may be suppressed іп a declaration context by чеш а subtype with 
the type бреве operator SHARED, as described on page 24.63. 
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checked after the assignment has taken place. Also note that not all 
functions which can change values are affected: in particular, set 
and setn are not. 


| Manipulating named types 


decltype is a file package type (Section 14). Thus all of the operations relating to file package types, 


e.g. getdef, putdef, editdef, deldef,”° showdef, etc., can be performed on decltypes. 


The file package command, DECLTYPES, is provided to dump named decitypes symbolically. 
They will be written as a series of decltype forms which will specify only those fields which differ 
from the corresponding field of their supertype(s). If the type depends on any unnamed types, 
those types will be dumped (as a compound type expression), continuing up the supertype chain 
until a named type is found. Care should be exercised to ensure that enough of the named type 
context is dumped to allow the type definition to remain meaningful. 


The functions getdecltypeprop and setdecltypeprop, defined analogously to the property list 
functions for atoms, allow the manipulation of the properties of named types. Setting a property 
to NIL with setdecltypeprop removes it from the type. | 


RELATIONS BETWEEN TYPES 
The notion of equivalence of two types is not well defined. However, type equivalence is rarely of 
interest. What is of interest is type inclusion, ie. whether one type is a supertype or subtype of 


another. The predicate covers can be used to е whether the values of one type include 
those of another. | 


covers[hi;lo] is T if hi can be found on some (possibly empty) supertype chain 


of lo; else NIL. Thus, covers[FIXP;declof[4]] =T, even though the - 


decltype of 4 is SMALLP, not FIXP. The extremal cases are the 
obvious identities: covers[ANY; anytype] — covers[anytype;NONE] — 
covers[x;x] for any type x = T. 


covers allows declaration based transformations of a form which depend on elements of the form 
being of a certain type to express their applicability conditions in terms of the weakest type to 
which they apply, without explicit concern for other types. which may be subtypes of it. For 
example, if a particular transformation is to be applied whenever an element is of typc NUMBERP, 
the program which applies that transformation does not have to check whether the element is of 
type SMALLP, LARGEP, FIXP, FLOATP, etc., but can simply ask whether NUMBERP covers the 
type of that clement. | 


The elementary relations among the types, out of which arbitrary traversals of the type space can 
be constructed, аге made available via: 


95 Deleting а named type could possibly invalidate other type definitions that have the named type as a subtype or 


supertype. Consequently, the deleted type is simply unnamed and left in the type space as long as it is needed. 
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subtypes[type] | returns the list of types which are immediate subtypes of type. 
supertypes[type] | returns the list of types which are immediate supertypes of type. 


THE DECLARATION DATABASE 


One of the primary uses -of type declarations is to provide information that other systems can use 


to interpret or optimize code. For example, one might choose to write all arithmetic operations in 


terms of general functions like plus and times and then use variable declarations to substitute more 
efficient, special purpóse code at compile tim time based on the types ОЁ the operands. To this end, a 


data base of declarations is made available by the Decl package to support these operations. 


decloffform] | . returns the type of form in the current declaration context. If 
T | form is an atom, declof will look up that atom directly in its 
database of current declarations. Otherwise, declof will look on the 

property list of car[form] for a DECLOF property, as described 


below. If there is no DECLOF property, declof will check if | Я 


car[form] is one of а large set of functions of known result type 
(e.g., the arithmetic functions). Failing that, if car[form] has а . 
. MACRO property, declof will apply itself to the result of expanding 
(with expandmacro, Section 18) the macro definition. Finally, if 
form is a Lisp program element that declof "understands" (е.р., а. 
cond, prog, selectq, etc.) declof applies itself recursively to the 
part(s) of the contained form which will be returned as value. 


DECLOF val | 222 allows the specification of the type of the values returned by a 
| particular function. The value of the DECLOF property can be “ 


either a type, і.е. a type name or a type expression, or a list of the 
form (FUNCTION fn), where fn is a function object. fn will be 
applied (by declof) to the form whose car has this DECLOF property 
on its property list. The value of this function application will then 
be considered to be the type of the form. 


As an example of how declarations can be used to automatically generate more efficient code, 
consider an arithmetic package. Declarations of numeric variables could be used to guide code “ 
gencration to avoid the inefficiencies of Interlisp’s handling of arithmetic values. Not only could | 

the generic arithmetic functions be automatically specialized, as suggested above, but by redefining 
the BINDFN and the SETFN properties for the types FLOATP and LARGEP to re-use storage in the 


19, The "current declaration context" is defined by the environment at the time that declof is called. Code reading . 
Systems, such as the compiler and the interpreter, keep track of the lexical scope within which they are currently 
operating, in particular, which declarations are currently in effect. Note that (currently) declof does пог have access to | 
any global data base of declarations. For example, declof does not have information available about the types of the 
arguments of, or the value returned by, a particular function, unless it is currently "inside" of that function. 
However, the DECLOF property (described below) can be used to inform declof of the type of the value returned by 
a particular function. | 
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appropriate contexts (1е., when the new value can be determined to be of the appropriate type), 
tremendous economies could be realized by not allocating storage to intermediate results which - 


must later be reclaimed by the garbage collector. The Decl package has been used as the basis for 
several such code optimizing systems, - 


DECLARATIONS AND MASTERSCOPE _ 


The Decl package notifies Masterscope about type declarations and defines a new Masterscope | 


relation, TYPE, which depends on declarations. Thus, the user can ask questions such as 


WHO USES MUMBLE AS A TYPE? — 
DOES Ғ00 USE FIXP А5 А TYPE? 


and so on. . 
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APPENDIX 1 
CONTROL CHARACTERS 


Several control characters are available to the user for communicating directly to Interlisp, 1е., not 


through the read program. These characters are enabled by Interlisp as interrupt characters, so _ 
that Interlisp immediately "sees" the characters, and takes the corresponding action as soon аѕ 


possible. For example, control characters are available for aborting or interrupting a computation, 
changing the printlevel, etc. This section summarizes the action of these characters, and references 
the appropriate section of the manual where a more complete description may be obtained. 
Section 16 describes how these interrupt characters can be disabled and/or redefined, as well as 
how the user can define his own new interrupt characters. 


CONTROL CHARACTERS AFFECTING THE FLOW OF COMPUTATION 


1.  control-H (interrupt) at next non-linked function call, Interlisp goes into a break. 
Section 16. 
2.  control-B (break) computation is stopped, stack backed up to the last function call, 


and a break occurs. Section 16. 


3. control-E (error) computation is КҮЗЕН stack backed ир to the last errorset, and 
NIL returned as its value. Section 16. | 


4.  control-D (reset) computation is stopped, control returns to evalgt. 
5.  control-C In Interlisp-10, computation is stopped, control returns to the operating “ 


system. Program can always be continued without any ill effect with © 


CONTINUE command. 


If typed during a garbage collection the action of control-B, control-E, and control-D is postponed 
until the garbage collection is completed. 


Typing control-E and control-D causes Interlisp to clear and save the input buffers. Their contents 
can usually be recovered via the $BUFS (<esc>BUFS) command, as described in Section 22. 


І/О CONTROL CHARACTERS 


1. «deb! clears terminal input buffer. For example, <del> would be used if the 


user typed ahead while in a garbage collection and then changed his 
mind. Section 2. A bell is rung when the buffer has been cleared, so that 
the user will know when he may begin typing again. 


Note: a sudden burst of noise on a telephone line frequently causes Interlisp to receive а <del>, 
since the code for <del> is 1770, i.e., all 155. This causes Interlisp to (mistakenly) clear the input 


buffer and ring a bell. If Interlisp seems to be typing many spurious bells, it is a good indication 
that you have a bad connection. 
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2. control-O clears teletype output buffer, Sections 2 and 14. 
3. control-P changes printlevel. Section 14. 
4. control-A2Q,?W line editing characters, Sections 2 and 14.4 


5.  control-R | causes Interlisp to retype the input line, useful after several control: A’s, 
e.g., if the user types | 
«DEF INEQ( (LAMDA\A\DBA\Acontrol-R, Interlisp 
types 
DEFINEQ( (LAMB. 


6. control-V on input from the terminal, control-V followed by A, B, ... Z inputs the. 
corresponding control character, otherwise is a no-op. The control-V is 
not passed to the line buffer; the transformation takes place before that. 
Thus ABCtVD followed by two control-A's erases the control-D and the 
C. ТУ takes precedence over , i.e, ТУ inputs a control-C, ТҮС inputs a С. 


MISCELLANEOUS 
1. controlFT (time) prints total execution time for program, as well as its status, e.g., 
«КЕСІЛІМ() 


collecting lists 

COLLECTING AT 26310, LOAD 0.1, UTIL 37.8% 

7819, 10379 FREE CELLS © 

10379 

-LOAD(FOO) 10 WAIT IN READ IN *EVAL ОТ“ IN LISPXBLOCK, LOAD 
0.1, UTIL 57.6% | | 

RUNNING IN EVAL IN *LOAD* IN LOAD, LOAD 0.1, UTIL 8.6% 


2. control-S® (storage) change minfs. Section 10. 
3. control-U? if typed in the middle of an expression that is being typed to evalqt, 


breakl or the editor, will cause the editor to be called on the expression 
when it is finished being read. See Section 22. | 


2 < del > for Interlisp-10 on TOPS-20. 

3 Control-U for Interlisp-10 on TOPS-20. 

Control-A, Q, R, V, and W are not interrupt characters, since their effect does not take place when they are typed, 
but when they are read. Section 14 describes how these pseudo-interrupt characters can also be disabled and/or 
redefined. Note that control-A, Q, R, V, and W have their special effect only on input from the terminal. On input 


from files, they are treated the same as any other character. 


Users who prefer the format used by the TENEX or TOPS-20 exec, i.e. RUNNING AT --, LOAD --, UTIL --, 
USED -- IN --, may disable the Interlisp Control-T by performing interruptchar[20]. | 


6 Сопшо-Х for Interlisp-10 on TOPS-20. 
Control-N for Interlisp-10 оп TOPS-20. 
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4. line-feed edit command. Aborts printout and moves to next expression and prints 
it. Section 9. | 
5. сопио!-Х8 edit command. АБогіѕ printout and moves to previous expression and 


prints it. Section 9. 


6. control-Z? 0 edit command. Aborts printout and moves to last expression of current 
expression and prints it. Section 9. 


7.  control-Y read macro. Returns result of evaluating next expression read as though it 
had been ee Section. 14. 


The function performed by < line-feed > , <control-X>, < control-Z>, and <control-Y >. may 
be easily assigned to other control characters via the function settermchars described in Section 14. 


Control-A for Interlisp-10 on TOPS-20. 
Control-L for Interlisp-10 on TOPS-20, 
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ENDCOLLECT(UST TAIL) ius ов wes nine es 6.3 
ENDFILE[TILET. 459919 ERE RET ӘЖК a Re об 14.42 
ENTRYASIHISTUX] 3544 ЕКЕ ВМОРО еа АРА 22.40 
ENVAPPLY[ FN; ARGS; АРОЅ; CPOS; AFLG;CFLG] SUBR ...... 12.9 
ENVEVAL[ FORM; APOS; CPOS; AFLG: CFLG] SUBR- закажаа 12.9 
EQ[X;Y] ЗИВК .................. РУР — eat 5.10; 2. 2 
FOUENGTHIOG NT жеее t ров c wees rn 6.6 
EOMEMBEX SY] эккени» жж e niter] eR Ра we ee нова 5.12 
FOPIXSY].SUBR. Suse века E E e вас d YR ee s 6.10; 13.3,6; 3.3, 
МИ = ______- __ = CN пи. 752214 
EQUAL[X;Y] SUBR ................................. 6.10; 2.2; 13.1 
FOURLALET Y: | oat dace ТИР ТИ жари d ECL ER на бо 5.11 
ЕОШАГНЕХСУ DEPTH). 54, зала tei ec a n 5.11 
ЕКВОВГМЕ551; МЕ552; МОВВЕАКТ ......... ракави 16.10,4,6,9 
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do IB M ——————————— 
ERRORNE T SUBR ТРЕКИ АЕК КК а acce 
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ERRORSTRING[N] ИВА ............................. 
ERRORX[ERXM] ........ ЕИ поста а ма ни пре 
ERRORIT ЗОВ. еса nich cart шк o Sed жазары» 
ERSETOFERSETXT NG damos родова ЕАС ЕНЕР 
КАО ЦЕНИ oreraa ras ен ИЕ УСЗН Рр 
ESCAPEFFILG) SUBR. асо cuted UNIO UE PER катый 
ESUBST[NEW;OLD;EXPR;ERRORFLG;CHARFLG] ........... 
ЗЛЛЕРШЕЛІ; зе а аео 
EVALA[XSAT SUBR- плина конака ината НЕР 
EVAPOT[LISPXIDI уеже ch whew ан ыдыра 
EVALV[X;POS] ЗОВА ...................... MENS, 
EVERY[EVERYX;EVERYFNI;EVERYFN2] ................. 
EXPANDMACRO[FORM;QUIETFLG] ................. Don 
EXPRP[FN] ЗОВЕ ........................... MOM 
ӨЗІ ТТК ФКИ ИЕККЕ 6 


FASSOCIKEYT КАБ ЕЕ] - сазаны в eso hare d Re area 
FAULTAPPLY[FAULTFN;FAULTARGS] .................... 
FAULTEVAL[FAULTX] Мой ........................... 
FBOX[N] э «э э э ө |] э э э э э | э э э э ө ө * э э э э ә ө ө э э э э ө ө ә э ө ө э э э 
FCHARACTER[N] ЗОВЕ .............................. 
FDIFFERENCE(X;Y] ....................... TTE 
FETCHFIELD[DESCRIPTOR;DATUM] .................... 
FFILEPOS[PATTERN;FILENAME ; FILESTART; вени, SKIP; 


TALLI CASEARRAY I , iex 805% КАРЖЫ нов | 


де ру РТО И DM 
FGREATERP[X;Y] БИВА /..................;........ ња 
FIELDLOOK[ FIELDNAME] ............................ 
FILDIR[FILEGROUP;FORMATFLG] ..................... 
PILECOMSDEIEESX] 5а зақ AX ымы RES dA 
FILECOMSLST[FILE;TYPE;FLG] ...................... 
ЕШЕСИРАТЕРГХТНЕЯ-; 2а арка та Korb ese ааа 
БІБЕБАТЕГЕ ШЕСІ 25 зекет зу руэн 
FIEEFNSESTEFILET. с озова a Opa реа РУз NEED 
FILENAMEFIELD[FILENAME;FIELDNAME] ............... 


FILEPKGCHANGES[N] *__............................. | 


FILEPKGCOM[ COMNAME;PROP1;VAL1;...;PROPn;VALn] * 
FILEPKGTYPE[TYPE;PROP1;VAL1;...;PROPn;VALn] * . 
FILEPOS[PATTERN;FILENAME;FILESTART;FILEEND; SKIP; 
TALL CASEARRAY | bees Ea куьн qne da 
PELES ш rr Lo 
FINDCALLERS[ATOMS;FILES] ........................ 
FINUPFTIEEDTFILESNSELGOT] 4 ad e тақ OR ERR 
FEXTA T auxi ра erede = = = 
FIXEDTTIDATELEXPR]- зне зо A Ou us 
КЕРА. Жекен ata е ТЕ 
FIXSPELL[XWORD;REL;SPLST;FLG; TAIL; FN; ТТЕРІ 6; 
ООМТМОМЕТОРЕ 6; CLST; APPROVALFLG] | о d 
ЕЕ айнаны аны ыла ораса ыр ated onset 
ЕБЕНСІШЕХІ аб елисни prada арада ce СЕН алы раты 
PLESOELASY асар a Аа ard 
PORTO КЕРНЕГЕН КТК оо ее 
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„11; 7,5; 16.3-4,10,- 


10; 15.5; 16.10 
12; 5.5; 16.11 


63: 6.5; 22.13 
6; 2.3,6; 4.1; 16.11 


13: 2.2 | 
1: 17.3,10,14; 18,17 
1,6: 17.3,10,14 


.79,60; 18.5 


ГЕОКТРГХЯСӨШЕН: нео аткан тысына ее кка 
EETEMEIEFORMAIBITS]- какао ЕБЕ 
E X;MIN;P2FLAG;CENTERFLAG;FILE] 

FMAX KI Ka pee АП] ТОК ux даша шы катыны 
ГМЕМВГХОҮ уузга емайл веки Res 
ЕМИ ХО ХО И ОД САП) сеанса ТОНИНИ 


МЕС а не ет ПРЕ РА arn a ра cons 


FNCHECK[ FN; NOERRORFLG ; SPELLFLG ; PROPFLG; TAIL] 

КҮШ NI с-сы ы се и ул 
ЕНТҮРГЕНІ ор рак ку ы АЛЫШ Аы аа Кака 
ҒОМТМАМЕГМАМЕД .................................. 
FONTSETLNAME] оа е ҚЫ e ЕЙ Eee 
FORCEOUT[CONNECTION/FILE] ....................... 
FPLUSTX1;X2;...;Xn] $0В88*__....................... 
FQUOTIENT[X;Y] SUBR /............................. 
FRAMESCAN[ATOM;POS] SUBR ........................ 
FREEVARS[FN;USEDATABASE] ........................ 
FREMAINDER[X;Y] ЗОВЕ ............................ 
FRPLACADXS Y] СИВИ чеки тии рент dao dos 
FRPLACD[X: Y] SUBR МИККИ pe cha epe е 
FRPLNODE(X;A;D] ................................. 


FRPUNODEZEX Y] озара сайы тема OR above datas 
V ЕВРТОГМ; FORM1;FORM2;...;FORMn] МЕ“ .............. 


ЕТІМЕЅ[Х1;Х2;...;Хп] SUBR* ...................... 
ЕТРГНОЗТ ; ЕТ! Е; АССЕЗ8 ; USER; PASSWORD ; ACCOUNT; 
ВО КОЛ |с жуы tints aan Ра РЕ 


JFUELNAME[ X:;RECOGI ............................... 


FUNCTIOND EN ENVIT NG ~ osse кдын киик а ккк» 


. ә 9 ә ө е э ө е ә е э 9 е е з 9 э ө е 9 9$ 9 8 е э э 9 ө эз 5 5 э э э э э э 


бАТМ$РАСЕ[] ............. Жетен TIT 
D NCC ы ноз MMC DTE Ини 
GCGAGE MESSAGE): елук cua вкда ius equa ween da dU. 
GCMESS[MESSAGE#;STRING] ЗИВВ .................... 
GCERP(NG ЗОВЕ 54:35 рака суа кже pe ыиык seco 


GDATE[DATE;FORMATBITS;STRPTR] .................... | 


СЕМЕКАТЕ | НАМОГ Е; VAL] .................. козе е 
СЕМЕКАТОК | ЕОВМ## ;COMVARH#] NL ............. TT 
GENSYMECHAR] Su bere ea ceo RON Ee тысы inae oa nite es 
СЕО: ux xu Eo We cs сыза 7 
GETATOMVALTAIM): SUBR. ............................ 
GETBEKT NT ЗОВЕ 2 уы ыы WO 
GETBRKTRDTBL]. SUBR .............................. 
GETCOMMENT[X;DESTFL;DEF] ........................ 
GEICONTROLLETBL. звезда жата SEE POS 
ӨЗІНЕШЕСІ itn КОК КЕТЕР ТК ac ard 
GETDECLTYPEPROP[ TYPE; PROP] RU NE a ақы ак 
GETDEF[NAME;TYPE;SOURCE;OPTIONS] ................ 


GETDELETECONTROL[TYPE;TTBL] ..................... 
GETDESCRIPTORS[TYPENAME] 2................. MORS 


GETECHOMODE[TTBL] ............... eee eine Du 
GETEOFPTR[FILE] ОВА ............................ 
GETFIELDSPECS(TYPENAME] ......................... 
GETFILEINFO[FILE;ATTRIB] ........................ 
GETFILEMAP[FILE; FL] ............................. 
GEFFILEPTREFILE] SÜBR ........................... 
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13.6 Ec 
14.35; 3.4 © 
23.50 

13.6 Е 
5.12; 2.2 

13.6 | 

13.5 . 

17.20; 8.4; 17.21 
6.6: 2.2 

8.3: 4.2; 8.1-2,4,6 
14.52 

14.52 

24.47 


11.1; 12.10; 11.3-4, 


12.14 | 
10.3; 3.2; 10.4; 15.15, 
18.13: 19.3-4 
13.6 
5.6 
21.6: 16.7 
14.14 
14.45 
14.33 
8.2; 2.3,5, 8.1,6 
24.65 
14.69 
14.31 
3.8 


GETHASH[ITEM;HARRAY] SUBR ..... TREES И 
GETHASHFILE[KEY;HASHFILE] ....................... 
GETELISDOGPROPS]: 22042 ае 6а PORRO а 
GETPAGE[HASHFILE;N] ............................. 
GETPASSWORD[DIRECTORYNAME] ...................... 
GETPNAME[FILEADR;HASHFILE] .......... BTE i 
GETPROP[ATM;PROP] ............................... 


BETPROPLISILAIMT serentis тах ыз ви бб Аы aes | 


GEIRATSELTIBL]I- 752 сы мысы ааа KU S races 
GETREADTABLE[RDTBL] SUBR ........................ 
GETRELATION[ITEM;RELATION; INVERTED] ............. 
GETSEPR[RDTBL] ОВА ............................. 
СЕТЗУМТАХ СН; TABLE] ............................. 
GETTEMPLATE[FN] ................................. 
GETTERMTABLE[TTBL] SUBR ......................... 
GETTOPVAL[ATM] SUBR ................ MEER 
GETTYPEDESCRIPTION[TYPE] ........................ 
CECT ВОВЕ РР ИКЕ AO Or Salou. 
GNC[X] SUBR  ..... ЕТКЕ ТИРЕ ЕТКЕН 
ОПГАДСТӘШЕНЯ-?; 2553: ocd ac aie сатаа fc bates 


GREATERP[X;Y] SUBR .............................. | 


GREET[NAME; FLG] ................................. 
GTJFN[FILE;EXT;V;FLAGS] ......................... 


HARRAY[N] ЗОВЕ ............................... TEN 
НАВВАҮР[Х] ........... еа 


HARRAYSIZELHARRAY | е sie лана ава 30808 ки Бч | 


HASDEF[NAME;TYPE;SPELLFLG] ...................... 
HASHFILENAME[HASHFILE] .......................... 
ПДЗПЕТЕЕРИХ ИТ КЕЛМЕ ИЕК КО ЫРДА 
HASHFILEPROP[HASHFILE;PROP] ..................... 
HASHFILESPLST[HASHFILE] ......................... 
ЧСОРҮАБ ГҮ weds осн изат ia o RS кы den ки сека брака бы бы 
HELP[MESS1;MESS2] ............................... 
HERALD[STRING] ОВА ............................. 
HISTORYFIND[LST; INDEX ; МОО ; EVENTADDRESS; 
LISPXFINDFLG] ........................ 
HISTORYMATCH[INPUT;PAT;EVENT] ................... 
HISTORYSAVE[HISTORY ; ID; INPUT1; INPUT2; INPUTS; 
PROPS лымын ева шы сеет 
HOSTNAME[ÇHOSTN] `................................. 
HOSTNUMBER[] .................................... 
HPRINT[EXPR;FILE;UNCIRCULAR] .................... 
HREADI FICE). Деан ора ое аа dA ATE HE E расын 


IBOXLNT-, sca oS. ER даска LR бағатын тыш Бәлен 
IDATEID]. ата en nn ЕРСАРЫ E eer СГ 
ТОТРРЕКЕМСВЕ SY E. сокты ҚАЗ ert SS TE 
IEQP[N;M] SUBR ............. EEEE EEEE — 
IGEOTLXAY] . wie каква eee ee ee OE ee ees 
EGREATERPL ASV] SUBR. асамыз зии па D RE 
EEEOEX GY |: tere XO cee, Got E as bln p ұла а ЗЫ den 
ILESSPI X YT пина КИ и АЕ eres 
MAKERS ХА ОЛИ И али ао и wa aaa ea 
IMIN АЛКА АП рға қы NC eh Жа 
ІМІММӘГАІ: 65-ы ва а аа acad c eed 
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6.4; 14.23 


22.40 


21.9 


INFILECOMS?[NAME;TYPE;COMS;ONFILETYPE] .......... 
ІНЕТ-ЕРГЕНЕТ SÜBR .............................. 
INPUT[FILE] SUBR _................................ 
INREADMACROP[] ОВА ............ РГЕН 
INTERRUPT[INTFN;INTARGS;INTYPE] ................. 
INTERRUPTABLE[FLG] SUBR ......................... 
INTERRUPTABLEP[] SUBR ........................... 
INTERRUPTCHAR[CHAR ; TYP/FORM; А нт КЕТУ 
INTERSECTIONDGY] ара елите кон vet ey 
ТОБЪСЕЕРЪВЕТЗОИВНЕ НКИ рыйк au AG ADU cad 
IPLUS(X1;X2;...;Xn] SUBR* _...................... | 
SOBOFIENI[X;Y] SBBR. 522022 шыде оваа Валер 


IREMAINDER(X;Y] ОВА ............................ | 


ITIMESIX1:X2 ко КОЛ SUBRE а а Ed Pea GP EC 
I.S,.OPR[NAME;FORM;OTHERS;EVALFLG] ................ 


JFNS[JFN;AC3;STRPTR] ............................ 
јој: ни aa оо КЕТЕДІ көтен 
ЈУГ ISYSNAME;AC1;AC2;AC3;RESULT] ................. 
JSYS[N;AC1;AC2;AC3;RESULTAC] ЗОВА ............... 
JSYSERROR[ERRORN] ............................... 


KFOREDFORK]. 5-52 ева ете о, n 
KWOTEING зони аи ли ни о ви ian dccus oe ie паша 


КРЕМ 
LASTCEREEE? БИВА” genet pee Riko isis ni А Заев раа 
LASINELSNT .................... х 
BOKER TERS а ANF ав ки ык» А ыйык ашк e 
ССОНСЕРТЕ XT ааа е Ин ИЗ Аја ЫҚ» 
LDIFFDIXCYSZ] . ен неона а авина Сы Ба PEE 
[ОТЕЕЕЁВЕМСЕ[Х;Ү] ................................ 
EENGTBDX. че tee оро ЫЛЫ bte ab К 
LEOLA | © ырымын кана chon Nate aia Ыр а а S 
СР YI с ж тана На aie alee = Е 
LINBUFTFFEG] SUBR 5,2245 збек жыша кз тъста 
LINELENGTH[N] SUBR .............................. 
ЕЛМКТОТТИГІТИЯІ 20055 | по и T alee’ 
LINKTOUSER[USERT. 5а б е а boa Rep ое 
LISPX[LISPXX;LISPXID; LISPXXMACROS; LISPXXUSERFN; 
АЗРА О а Бани е оил ара ил ФА 


ээ • 1. $ ое э 9 9 9 э е с ө с ө е а 9 с с э о с о о * 9 с э е э о 59 о с эз э э э @ с 9 э э 
ее 8 • • 9 9 ә е ә 9 е ә ә ә 6 э 9 9 @ е е в е э е ә э е ә ее е е $9 е е 9 9*9 Ө > э а ее 


• • 9 е 9 9 b э э э 9 ө 9 э э е е е 9 е е 9 е ә е е е ле ә е ө 5 г е е е ө ә э 5 э э э э 


LISPXEVAL[LISPXFORM;LISPXID] .................... 
LISPXFIND[HISTORY; LINE; ТҮРЕ; BACKUP; ОПТЕТЕ 6 ] А 
LISPXPRINT[X;Y;Z; NODOFLG] —— HMM 
LISPXPRINTDEF[EXPR; FILE;LEFT;DEF;TAIL;NODOFLG] .. 
LISPXPRIN1[X;Y;Z;NODOFLG] йл оле ada p aw OR 
EESPXPRINSIX;Y;ZSNODOFEG]. viii x ir eae ee C 
LISPXREAD[FILE;RDIBL] axo eR e елык века 
LISPXHEADPDEREG. зыта бота ин 
LISPXSPACESEX:YSZ:NODOFLG]. «vive ке ыт» 
LISPXSTATS[RETURNVALUESFLG] Uc вове e Oso Me eO ТОСЕ ТЕГЕ 
LISPXSTOREVALUE[EVENT;VALUE] .................... 
JAISPXTAB[X;Y;Z;NODOFLG] ......................... 
LISPXTERPRI[ X: YZ NODOFLG] аи ле E окното 
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| | LISPAUNREADELSTSEVENT), Gua сан оке ЫЗ 22.38 
LISPAWAITICHISTIATD:N] лары быз зара ыл we кои als 22,46 
EISPXZDXSENSVARS | 5546 клина Va wie slaw eee Rn 22.42,32 
ЛОРА Хе << ХО SUBRE iode E RO RR e oe фа 6.1; 3.5 · 
CYSTPILES PEERS NES. uus soma каже Буз . 14,66,64-65 
БТЭТЕТЕЕСІГЕЛЕРІ: ыса ҰҒЫ За ват ата 14.66 
МТӘТБЕТГЕЗТГЕРНӘРІ), uia eia Мах ЫБЫ» 5.13; 23.28 
LEISTGELTIEESTSPRÜPT маржа рани Да etate cs 5.13 
LISTPEX]-SUBR.. пар oe о кы кезе к оа cens 5.10; 2.3 
ӘЛЗІРШІІЕЭТІРЛОРЗУАГ ualet ao o Sun Res ыр 5.13; 23.28 
EISIPUTI[EST PROP: VALT ginea локви и x X Re а 9.13 
LELPIATOMI A] SUBR. visui eases PRA RR recs E жа 6.9. 
DPSHENSMTCSUBIU ъс оаза жакны шата икана 13.4 
LOAD[FILE;LDFLG;PRINTFEG] аъла ааа ERR 14.38; 2.9; 18.5 
EDADAM|[ |. « аа ави НЕ аа и ооа ЖЭ 21.8 
LOADBLOCK[FN;FILE;LDFLG] ................... зара 14.40 
ЕОЛЮРСОМРЕГРЖЕЕСЕРЕІӘІ езана дее е е еса 14.40 
LOADCOMPT[FILESEDELG) тозо оа оа vx вон 145841 
LOADDBI FILET неко teu е е сы Ұлман» 24.32 
( ОАООЕҒ [МАМЕ ; ТҮРЕ; SOURCE] ..................... алы 14.71 
LORDEFS ЕИЗ FILET «ао y 3i еа барано ад БА 14.40 
LOADFNS[FNS;FILE;LDFLG;VARS] .................... 14.39 
LOADPROMLFILE:FNSSEDFEG]-— iex ehem s 14.40; 18.8 
LEOADVARSILVARS;FILE;LDFLG] „зз rr n аа 14.40 | 
LOADT[FILE;LBFLG;PRIMIFEG ] i... якта ә 14.39 
BOC( КО SUBR xou nde ae Lice Qux eu пале а а HG: Rese ew ce 13.10,10 
КОСКМАР[Р1Ҥ]. оаа олана РЯ РРР 21.15 
СОС |. аза за лама атым Ва Фев Sune av ee жака 13.7 
БОСАМШАС АО шев Т ANT ЗОВК“ ` 5,28555% 6а ыт Ron 13.4 | 
LOGOREXL A2; An] SUBRE ризка i-e o oe DEI 13.4 | 
LOGOUT ЕТ 9086 да pog Ies вв вез оролун 21.4; 2.3; 21.8 
LOGXORLXIZX2 по ДП T SUBRE о oe veas 13.4 
LOOKUPHASHFILE[KEY;VALUE;HASHFILE;CALLTYPE] ..... 24.51 
LOWERCASELEFEGT 354% ы МЫ да a I Eee ER S Lees 09,04 
Boe ЕНЕГЕ. а та Аы аа А и ла БАЕТ 13.4 
Bog D ыле ыза ЕМ жик азы А e.. 13.4 
ESUBSTLINEW:OLDSEXPR] ux о ЕЗ ES x Res 6.4,5 
LACASEEX FEGT ipsae ob AOI Sa de e oon IC. чна 10.4; 9.50 
МАКЕВТТТАВЕЕГЕТМЕОТА || о AR RIED EE SS 10.7 
MAKEFILE[FILE;OPTIONS;REPRINTFNS;SOURCEFILE] .... 14.64-66; 17.21; 18.8 
MAKEFILES[OPTIONS;FILES] IARE 14.66 | | 
MAKEKEYLST[LST;DEFAULTKEY;LCASEFLG] ............. 17.29 
MAKENEWCOM[ NAME; TYPE;LISTNAME; FILE] ............. 14.76 
MAKENEWCONNECTION[ HOST; TYPE; SKT; SCRATCHCONN; 
WAITFLG] ......... наскоро ли ise ВО 24.46 
MAKESYS[FIEE] SUBR. (uu EG ж ва ак ви des 3.11 
MAP[MAPX;MAPFN1;MAPFN2] ......................... 11.2 
MAPATOMS[ EN] SUBR ^ а obo жие жа edo ава ы ет 10.4 
МАРВПЕЕЕКСОШТГОНГҮЛ „ен бега EA REX hs 21.13 
MAPC[MAPX;MAPFN1;MAPFN2] ........... c m жюз . 11.2 
MAPCAR[MAPX;MAPFN1;MAPFN2] ....................... 11.2 
MAPCON[MAPX;MAPFN1;MAPFN2] ....................... 11.2 
MAPCONC[MAPX;MAPFN1;MAPFN2] ......... rr ел 11.2 
MAPDL[MAPDLFN;MAPDLPOS] ......... Wah пе Eos 12.12 
MAPHASHLARRAY ;MAPHFN] ........................... 7.5 
MAPHASHFILE[HASHFILE;MAPFN] ..................... 24.50 
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MAPLIST[MAPX;MAPFN1;MAPFN2] ..................... 11.2 
MAPPAGE[PAGEZ;FILE] ..................... РОР 21.13 
MAPRELATION[RELATION;MAPFN] ..................... 20.20 
MAPRINT[LST;FILE;LEFT;RIGHT;SEP; РЕМ; LSPXPRNTFLG].. 11.3 
MAPWORD[FILEADR; FILE] ien mdi ica EEI и E 21.14 
. MAP2C[MAPX;MAPY;MAPFN1;MAPFN2] ................... 11.3 
MAP2CAR[MAPX;MAPY;MAPFN1;MAPFN2] ................. 11.3 
MARKASCHANGED[NAME;TYPE;NEWFLG] ................. 14.67 
MASTERSCOPE[.COMMAND] ............................ 20.19 
МАХ БА ЛЕ RIL они аба oe AER psa eae 13.7 
MEMBFX YT сұт как ван eed ae a Means Ee 5.12 
МЕМВЕНГАЕНІ aue клер ван ее ваен оао еа ФО Ee er s 5.12 
МЕМБТАТГРСТ; РСМ; FORK] ................... жы бары eee 24.44 
МЕКСЕГА; В; СОМРАКЕЕМ| ............................ 6.8 
MERGE INSERT[ NEW; EST ONEFEGT | ovr ке кы T 6.8 
MINT XI Хо eNO ЖТТ ТК epee 13.7 | 
MINFS[N; TYPE] Ер и И mA а wea Ra dE eL 10.13; 3.10-11 
MINUSEXT SUBR ени ot ane ete aw Oo S Re Ea атанға 13.6 
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MISSPELLED?[XWORD;REL;SPLST;FLG;TAIL;FN] ........ 17.18,21 
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MACHINE.DEPENDENT. PARAMETERS] очила СС ar ee 14.3 | 
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OPNIFNEIFICES TYPE |-SUBR оона аена ама» АІ 
OR[DX1:X2:. 553A] PSUBR™ „а лево вв вала 29511 
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PACKEXT SUBR. uersa euch wie te wed ee ER UE ERE E 10.2; 3.2-4,9 
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PRINTEXSTILESRDTBL] SUBR. ud ey x ба жк а |» 14.17; 3.1,5-6; 14.18 
PRINIBELUSLI |: авто ИКЕ карж асы "ava А 17.4; 14.18 
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REALFRAMEP[POS;INTERPFLG] ....................... 12.7 
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RELSTREPOS | SUBR uou eaa ыса тан ARR ACE SR 12.11,12 
RELSTKP[ X] -z RE SR И а CRUCE А OR КҮҮ 12.11 
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RESETTERMTABLE[TTBL;FROM] SUBR ................... 14.29 
RESETUNDOLXSSTOPPLGT | uiu te REED екы 22.43; 5.9; 22.34 
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SKREAD[FILE;REREADSTRING] rov PE TIS 14.16 
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Names of functions аге in upper case, followed by their arguments enclosed іп 
square brackets ||, e.g. ASSOC[KEY;ALST]. The FNTYP for SUBRs is printed in full; 
for other functions, NL indicates an NLAMBDA function, and * a nospread function, 
28.0. LISTFILES[FILES] NL* indicates that LISTFILES is ап NLAMBDA позргеад 
function. Words in upper case not followed by square brackets are other  INTERLISP 
words (system parameters, property names, messages, etc.). Words and phrases in 
lower case.are not formal INTERLISP words but are general topic references. Where 
there are multiple references for a single entry, the primary reference(s) appears 
first, and in bold-italic font. 
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CHARDELETE (syntax class) ....................... 14.30-31 
" CHCONEXSF LG: НОТВЕ | SUBR. ues RC em ығы 10.3 
CHCONITX] SUBR. iue m SUV d Mes cher elati pa eade 10.3 
CHECK (Masterscope command) ..................... 20.11 
CHECKCONNECTION[CONNECTION] ...................... 24.47 
СЕСКЕ Т CITY 22.38 
CHOOZ[XWORD;REL;SPLST; ТАП; ЕМ; ТІЕҒІ 6; МОВЕ 5; С 5Т].. 17.16 
СІРСЕНАКЕНИЯƏ8ТІ. оаза ваа Er S are dA дви es 24.19 
CIRCLPRINT[LIST;PRINTFLG;RLKNT] ................. 24.18,17 
cjsys package .............. CY uade —— —— е 24.35-36 
CL-(odit command) esso Cede о e RO ax ооо 9.52; 23.60 
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CEDISABEELOP T. |a n OCCORRE REL аи a Saree Eon өш 23.59 
CLEANPOSLSTUPEST азығы ы алы mE MER 12.17 
CLEANUPLFILES] МЕЧ | ране парне еа ава cor eae ara 14.66 
CLEANUPOPTIONS (file package variable/parameter).. 14.66 
CLEARBUFFETEESEUG]T SUBR Ане eap oe arx OO ей ж CAS 14.34; 22.26 
Clearing. input робом брк ак ааыа викаа око вео. 2.4; 14.19,32 
Clearing опро Duffer ааа ива en IER s |. 2.45; 14.19 
CLEARMAP[FILE;PAGES;RELEASE] .................... 21.14 
CLEARSTKLFEG] SUBRO: 225% DR E ORE Ro алы коала з 12.11 
CLEARSTKLST (system variable/parameter) ......... 12.11 
ӨЛІК А а пе па пе о = а 12.5 "E 
CLISP. eod e да OE rae Dedi An s To aS раса ww db qo "pr За aed 23.1; 11.3; 17.11-14, 

"cpm 23.2-61 
CLISP and COMP TIGR 02а аи бе тағы eres 18.4-5 
(CLISP ‘declarations. . TOP) аиша RC 23.22 
CLISP interaction with и$ег ..................... 23.52 
CLISP internal conventions ...................... 23.53 
CLASP: орегастой:. ла њи О ER E аа кеа RR Rel 23.51-52 
CLISP (Masterscope template) .................... 20.17 
CLISPARRAY (clisp variable/parameter) ........... 23.57,22,60; 24.2 
CLISPBRACKET (property name) .................... 23.55 
CLISPCHARRAY (clisp variable/parameter) ......... 23.55 
CLISPCHARS (clisp variable/parameter) ........... 23.55 
CLTSPDEC[DECEST] saws на лан aie inet o к крађи ама ок ~ 23.58,24 
CLISPFLG (clisp variable/parameter) ............. 23.56 
СЕЛӘРГОНТ ы мм сыз еке ru Rare oa S ины a ата 14.50 


CLISPFORWORDSPLST (clisp variable/parameter) .... 23. 


CLISPHELPFLG (clisp variable/parameter)  ......... 23.57,53 

CLISPIFTRANFLG (clisp variable/parameter)  ....... 23.59,22 

CLISPIFWORDSPLST (clisp variable/parameter) ..... 23.10 

CLISPIFYI XA: LT а о и матка nS OUT Ора 23.38, 58; 14.65; 23.25, 
———— у [IO бе 39-40 

CLISPIFY (makefilo орттоп): ee» па он eas 14.65; 23.40,60 

CLISPIFYENGLSHFLG (clisp variable/parameter) .... 23.59,21,39 

ELISPIPYENSLENS] NET 2% 555555 кажей кеши жез: 23.59 

CLISPIFYPACKFLG (clisp variable/parameter) ...... 23.59,39 


CLISPIFYPRETTYFLG (prettyprint variable/parameter) 23. 


CLISPIFYUSERFN (clisp variable/parameter)  ....... 23.60,40 
CLISPINFIX (property name) ...................... 23.54 
CLISPINFIXSPLST (clisp variable/parameter) ...... 23.55,7 
CLISPI.S.GAG (clisp variable/parameter) ......... 23.19 
СІЛӘрГЕсөгІУпеб? ccc лане CHO WE c rade жш Sie 23.31 
CLISPRETRANFLG (clisp Var dun рагашегө") —— caw 23.59,22 
CLISPTRANI X; TRANT зоте ао CR: ies 23.57 
CLISPTYPE (property name) TL decease ТТР, 23.53-54 
CLISPWORD (property name) ....................... 23.64; 17.12 
CLISPA. сале икки en Ыиык Ae ened ЫЛАР elec eer ee СЕНЫ ЫДЫ 23.23,60 
CLISP: (edit command) луы кз тақат ақыра 23.60,22 
СЕОСКГАИЗСӘЦЕН uo Ты ә» жн» мааа ЕР 21.3 
CEOSEALLT T rcm 14.6, 10 
CLOSECONNECTION[CONNECTION] ...................... 24,46 
CEOSEFTFILE]. азаны маты ака БӨЗ алын 14,5 
ӘШЗЕЕТЕРІНЕЙ ызы ваза лылы ЖЗА ала ане 14.5 
CLOSEHASHFEEELHASHFILE] 555555550 Ее А АЗ Саз 24.49 
CLUSERLA: X SUBR- ув ааа ево ме 10.15 
closing and reopening files ..................... 14.9-11 
CLREMPARSFLG (clisp variable/parameter) ......... 23.509,39 
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CLRAASHEHARRAY | ЗОВЕ. ............................ 7.4 
CL:FLG (clisp variable/parameter) ............... 23.59,39 
CNDIRTIDIR PASSWORD." маани леви вачи мата «жағы 24.43 
CNERLV (Syntax class) ew x EGER За аыр шз 14.30 
CODE (property name) ............................ 8.6; 3.14 
COLLECT (clisp iterative statement operator) .... 23.12 
collecting (printed by system) .............. bue ДОСТА 
СОМ (as suffix to file пате) .................... 18.6,22 
commands that move parentheses (in editor) dai ees 9.33-35 
comment DOTHLBFS окована новиве E а еде 9.53; 14.45 
COMMENT USED FOR VALUE (compiler error message) . 18.34 
COMMENTFLG (prettyprint variable/parameter) ..... 14.48,44- 45 
СОММЕМТЕОМТ „е... sess scales wn sees "—— rp 214.50 
COMMENTLINELENGTH (prettyprint variable/parameter) 14.51 
comments „Ста: 14511045) узек я oes eae ears 14.44-46 
COMMENTI[L;INBLOCKFLGO] 25255555545 к оа S Us 14.80 
СОтрасблтай заа айжан ак ка асра он 2725 3.10 
COMPARE[NAME1;NAME2;TYPE;SOURCE1;SOURCE2] ....... 14.71 
COMPAREDEFS[NAME;TYPE; SOURCES] ................... 14.72 
COMPARELISISLIXi;Y] еее сень Р ТУЕ 6.9 
СОМРИСЕГХНРНЕ |: в вае на ово eee ode ei OR 18.5 
сопра Fed. сеобе енн але а ере ер алаа жесе 10.8 
compiled TIe ааваа ESAE — m 18.5,7 
compired TUNCTIONS 529555588 воа нов ви Аы ECC 4.2 
COMPILED ON С ре ани xd ORBE ЫМ Et Ека АА as 18.5 
COMPILEFILES[FILES] NL* ......................... 14.66 
COMPILEHEADER (compiler variable/parameter) — a 18.5 
COMPILEIGNOREDECL (Decl package parameter) ...... 24.60 
COMDIIOC nico o ERU Жакканы ко е жыр MEET 18.1; 4.2; 18.2-36 
compiler error messages ......................... 18.33-36 
compiler functions орочени очај ақа na UR 18.5,6-8,19-20,22- 23 
compiler macros ..... EEEE E E E ЕИ РРР 18. 10- 12 
compt trer- РОШ а еа сао е ол за аялы 18.33 
COMPTVIOT questions was ew аваа eee вита 18.2-3 
COMP TIGR SIPUCLUDPB- uode а ры E CA C воа 18.23 
COMPILETYPELST (compiler variable/parameter) .... 8.7; 18.4,12 
COMPILEUSERFN (compiler variable/parameter) ..... 18.4,9 
COMPILEUSERFN (use by clisp) .................... 23.42 
COMPILE.EXT (compiler variable/parameter) ....... 18.6 
COMPILETI[EFN:DEPSCOREPEG] teens cad RE Rar 18.5 
compiling by datatype ........................... 18.12 | 
compiling СКЕЗР 552 Фен ШЕ ОАЫ 23.42; 18,4-5 
COMPETING: Tilos ipee eX ER ча ‚з ЗА ЧА R 18.6,7,22 
compiling FUNCTION. освоение тане .. 18.13 
comp*lang NLAMBDAS aes ex CONO NO LR e уе 18.3-4 
COMPLETEON (askuser option) ..................... 17.27 
COMPSETIFIEE:;FLG FILES] еза n ERG ae 18.2 
computed Macros, орања телесна век кв OCA AGE RARO RR оа 18.10 
(COMS x1 ... xn) (edit command) ................. 9.43 
COMS (file package command) .......... ig da DIS 14.57 
(COMSQ . coms) (edit command) ................... 9.43 
CONCATEX1:X2:. SAN] SUBR*- usus ace» Ақы y ано 10.5; 3.6; 10.8 
CONDILCISTC2 ъс CNT FSUBRE aise scents eas бака ет) 5.3; 4.3 
cond :Стабѕе: ibd ied As ie Aw OS Ерзат eas 5.3 
CONFIRMFLG (askuser option) ..................... 17.26 
conjunctions (in Masterscope) ................... 20.9 
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| CONS(ASVISSUBR: 4446-50. a aww аз ыза ыы RU E E 5.1; 3.5,9 

CONS algorithm 4455555 СЕЗЕ РЕ РЫСЫ a 5.1 

CONSCOUNTILNI SUBR. пратени жк OC wee eta а 5.1; 10.14; 21.3 

ООМӘТАНТГАЙ” 55,5% 245584 ace risi ӨТТЕ” 18.11 

constants іп compiled соде ...................... 18.11 

constructing lists (in clisp) ................... 23.10 

CONTAIN (Masterscope relation) .............. wes 055 

Context Switching оину EE 12.6 

CONTIN (prog. asst. command) .................... 20.25; 21.8; 22.28 

CONTINUE SAVING? (printed by system) ............ 22.41,31 

CONTINUE WITH T CLAUSE (printed by dwim) ........ 17.6. 

CONTINUE (ТЕМЕХ command) ........................ 2.3,9; 21.4; А1.1 

continuing an edit session ...................... . 9.48-49 

CONTROL[FLG;RDTBL] SUBR ................ nre 14.33; 2.4; 14.12,14,32 

СОПТГОЛ Chalm . зое v Rex RA VS d АТ XE ND асы 12.5 

control character echoing ....................... 14.30 

control! “Characters: осе са сенка rw UA re deus A1.1; 2.3-4; A1.2-4 

СОПЕГОТЕА: aae ques d AR ae HERR КАН ӨЗ Ы Ж» 2.4; 14.32,11-14,29-31, 
rere | 33; A1.2 

control-A (TOPS-20) (edit command) .............. 9.14; A1.3 

СОПЕГОГЕВ: fc ... 16.2,3,5-6; 21.3; А1.1 

СОЙТГОТЕС ао std oa e eee Pare A P 2.3; A1.1; 21.7 

СОП СЕГО chere me аддын Аас OO era PIER 2.3; A1.1; 9.47, 
omm 14.34-35; 15.4,14, 
ыы Шалы коли ле CEN E пак 16.2,4,11; 18.4-5, 
ҚЫ d ле ОЛКУ ан а OU ee 21.3: 22.26 

СОПЪГО | ЗЕ: 45555 азығы ЕЗ ЫЫ RENS ЕК Ы ы Жа 16,2; 9,2; 14.34; 15.4, 
салыт қан Канта жама ыы ГЕ ТТ 17; 16.10; 17.4-5,10, 
и кл Залы Ша pee = = | С . 21.3; 22.20; А1.1 

control-E (typed to edita). ...................... 24.10 | 

control-F (in file name) ........................ 14.2 | 

control-G (use in history list) ................. 22.26,18 | 

COBÍPOlISH uada рана e wis cx тык оа ву 16.2; 10.14; 14.34, 
РК и ЛУУК кл“ Г КГ ЛК EE 15.14; А1.1 

СОПЪГОТ С: еі ЕЗ ЫНЫ OE NR Ын жые n 23.46 

control-L (TOPS-20) (edit command) .............. 9.14; A1.3 

cODtPol-N LIOPS-20)-. nah cette ase pie bU VET PTS 2.4; 22.27; A1.2 

СОПЕСӨЛЕІ << 2 Хе s ps acu а ке БА 2.4; 14.19; А1.2 

СӨПЕРОТЕР; 5 2 сола ак зе СО а Xa 14,19,34; 15,9; А1.2 

CONFON сыз осы па ко = d a = = ЫЙ 2.4; 14.32,11-14,29-31, 
Ек ОТ КҮ КО УЛУГ Г ЛЕ ЕТ 33; А1.2 

CODnLPOl*"R. рана ои s "m II A1.2; 14.30 | 

e RPIE d" 10.13; 14.34; А1.2 

Controler оаза гафови кани ва d ME Ns A1.2 

CORTE ON SU) 25 s xcv ec CY кке LOT =. о 2.4; 22.27,37; A1.2 

СОВЕКОТ “И (TOPS*20). со ни X 79 затын е 2.4; 14.30; А1.2 

СОП СРО uude v a e види алт ——— ығ» A1.2; 2.4; 14.11,13-14, 
аты За Қы пе ak ee 30 

CODLlOTL-W... Leger кира T weer eee она ве 2.4; 14.12; A1.2 

control-X (edit command) ........................ 9.14; 14.36; A1.3 

control]-X-CTOPS-20) | ix ves toes ж Лл TC 10.13; А1.2 

control-Y (as a read-macro) ..................... 14.27,36; A1.3 

control-Z (edit command) ........................ 9.14; 14.36; A1.3 

control-Z (10PS-2U0). scere RV ҚЫНА epa Eu 2.4; 14.14,32; A1.1 

COPYDXT сулары йа ноа de HU S eames 6.4 

СОПУ", рата а ааа пп obe Ж 6.4,1,5 

COPY (DECLARE: option) ^ uoces ace v ORENSE Каро ва 14,59 
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COPYALLI X]. езара А teow ы ears 6.4; 23,33 
COPYALLBYTES[FROMFILE ; IOFIEESBYTESIZE] 35255555550 24.43 
СОРХАВВАУРАНД:. з exi nice De c Ae hac ваа я .... 10.10 
COPYBYTES[SRCFIL;DSTFIL;START;END] ............... 14.9 
COPYDEF[OLD;NEW; ТҮРЕ; SOURCE;OPTIONS] ............ 14.70 
COPYHASHFILE[HASHFILE;NEWNAME;FN;VTYPE] ......... 24.50 
COPYING (record package) ........................ 23.33 
COPYREADTABLE[RDTBL] SUBR ........................ 14.24 
 COPYSTK[POS1;POS2] SUBR ......................... 12.11 
COPYTERMTABLE[ TTBL] SUBR ........................ 14.29 
COPYWHEN (DECLARE: option) ...................... 18.7; 14.59 
COREVAL[X] NL ................. Т does aet Карыз 21.3 . 
COREVAL (property name) ......................... 18.27,28-29; 24.10-11 
COREVALS- эрекел EMO SS UE RNC ЫН ACER Фани өй 18.27 
COREVALS (system variable/parameter) ............ 18.27 
COROUTINE[CALLPTRZ7 ; COROUTPTRZ7 ; COROUTFORMA# ; 

ENDFORME*K] NE. ose Erb RR heme а Жы 12.15 
COPOUTINGS, 22254260942 = eo VR OA rt doen 12.15,4,13 
COS[X;RADIANSFLG] ............................... 13.7 
СООН рона оао осле ава аео ва 6.6 
COUNT (clisp iterative statement operator) ...... 23.12 
COUNTDOWN[XSN] анаа 9 винова n 9c 6.7 
COUTFILE (compiler variable/parameter) .......... 18.33 
COVERSIHISLOT]: xd = каса EUER EEUU как 24.65 
CQ (in an assemble statement) ................... 18.26 
CREATE NOT DEFINED FOR THIS RECORD 2. message) 23.30 

. CREATE (Masterscope relation) ................... 20.5 
CREATE (Masterscope template) ................... 20.17 
CREATE (record package) ......................... 23.31-33 
CREATEHASHFILE[FILE;VALUETYPE; ITEMLENGTH; 

Тантал т” es eis жк кирак» 24.48 
СТВЕМ: {syntax class} chest stew dew иа Rob de кж жа 14.30 
curly brackets (use with ftp package) ........... 24.45 
current declaration context ..................... 24.66 
current expression (in editor) .................. 9.2,3,6,8-14,16-23 
CURRENTFN (transor variable) .................... 24.24 
CV (assemble Macro) dele кв љети а кв ааа 24.36 
CV2 (dsSemble macro) ааа eh e ааа жек уз 24.36 
D (edit command) «sw анан RR RU ба wee E TIR 9.54 
DA (exec Command) ius нола ам QURE ACC t a 24.41 
DATA TYPES FULL (error message) ................. 16.8 
databasof[ns- PACKAGE. «iit x Se SO eso ae ae висина ко 24.31-32 
DATATYPE (record package) ....................... 23.29 
data-paths (in records in clisp) ................ 23.34,26 
data- typos оаа SOC C Ix “А АА ты ED I e oe J.1,2-7,9 
DATELFORMATBITS]-SUBR. «eL REC 545554 s ван 21.2 
DATEFORMAT[KEYWORD1;KEYWORD2;...;KEYWORDn] ...... 24.40 
dateformat раскаде ^ vea or ho еа ив а RC 24.40-41 
DATUM OF INCORRECT TYPE (error message) ......... 3.8 
DATUM (use in changetran constructs) ............ 23.38 
DCHCON[X;SCRATCHLIST;FLG;RDTBL] .................. 10.3 
РЕЛЕСІ ЖЕТГІ до RORIS 24.9 
debugging 205506 = REB RN AIEO RA СЕ 15.1; 2.6; 12.2 
DOC! package „=... кка RACE ERR RE ERE E зо моќ 24.53-68 
DECL (1n Decl package)- аот иаа чое ыз ж» 24.59 
declaration fault (in Decl package) ............. 24.54 
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DECLARATION NOT SATISFIED (error message) Tm 24.54 
declarations (in Clisp) постанак ки а esas 23.24,8,10,25 
declarations (in pattern match compiler) ........ 24.6 
DECLARE. 2245-4 xa pa eit heed ww aoa ras лан Biase See Ae eee ed 18.10; 14.58; 18.21 
DECLARE AS LOCALVAR (Masterscope relation) ...... 20.6 
DECLARE AS SPECVAR (Masterscope relation) ....... 20.6 
DECLARE (clisp iterative statement operator) .... 23.17 
DECLAREDATATYPE[TYPENAME;FIELDSPECS;FLG] ........ 3.7; 23.29 
DECLARETAGSLST (prettyprint variable/parameter) . 14.59 
DECLARE: ТА NUS ^ ssa ве а права прва тықта қалы аз 14.59 
DECLARE: (clisp iterative statement operator) ... 23.16 
DECLARE: (file package command) ................. 14.58,59 
DECLARE: (ЗП сотр тегу eek ков виа нев Rs 18.6,6 
DECLOFL FORM]: ооа odia free PC ta RU Gee bandes 24.66 
DECLOF-(property name). „ооа акаа sieis rererere. 24,66,66 
БЕСІ. ТУРЕГТУРЕМАМЕ ; TYPEEXPRESSION; РКОРТ ; МА 1; . | 
| PROPn;VALn] _............................. 24.63 
DECLTYPES (file package command) ico fut oe d bv ecd ha 24.65 
decltypes (in Decl package) ...................... 24.53 
DEFAUEFFONT. segs aw e VARY жй жаккы Ын DE do n 14.50 
DEFAULTINITIALS (editor variable/parameter) ..... 9.59 
DEFAULTMAKENEWCOM[NAME;TYPE;LISTNAME;FILE] ...... 14.72 
DEFERREDCONSTANTI[X T. us kv act nem tuna ROI eo n 18.12 
DEFEVAELTYPESENT. аа раене rdc Sex ate RUE reco 8.7 
DEFINELX:TYPE-IN]. зае Sb. воина kA RO ыы o xs 8.5; 2.5 
DEFINED, THEREFORE DISABLED ІМ CLISP 
(error messdg8B). 592555 сыла а ао ee eens 23.11 
DEFINEQ[X1:X2;...;Xn] NL* ....................... 8.6; 2.5-6 
defining file package commands ............... 2... 14.73-75 
defining file package types ..................... 14.72-73 
defining new iterative statement operators ...... 23.19-21 
DEFUISITES PROP] uev Pads eines Ааа em Ras 7.3 
РЕРЕРКЕМРГТҮРЕРЕНІ “шынар Wie. e a y xa s ede eres 14.22 
DEL (ехес command): ош а 99 век жығыла ICE PR RR RS 24.42 
DELDEF[ NAME; TYPE] 450256 5*4 а виа по каи 14.70 
DELETE: (edit. command) - od E ERU Wee и RT ыы 9,26,9,24 
(DELETE . 08) (edit command) ......... ОРУ 9.28 
DEEETECHAR (Syntax Class). оаа даи 14.30,29 
DELETECONTROL[TYPE;MESSAGE;TTBL] ................ 14.31 
DELETELINE (syntax class) зое вревата ақ 14.30,29 
DELFILE(FILE] ............. ст ТС 14.5 
DELFROMCOMS[COMS ; NAME ; IXPET лап» бака етке 14.76 
DELFROMFILES[ МАМЕ; ТҮРЕ; PELES ||) зоналы ЕЕ 14.75 
DELNOTE (transor command) SAU E p NA Ae Ee ead 24.28 
DELPAGE[PAGEZ; HASHFILE] ‘ъъ ава deed sas 24.52 
DELVER (exec command) ........ Trpo 24.42 
DESCRIBE (Masterscope command) .................. 20.11 
DESTINATION IS INSIDE EXPRESSION BEING MOVED 
(printed by odltOPD) oed shanks wee Eas 9.31 
destructive functions ,............. dv ACE EA S 6.3-4 is, 
DET (exec. command): ies 9955 кынкы RON RR RO 24.41 
DETACHE | cunas оь ERR HOC алы ара оа 24.43 
ВЕТАСНЕВРЕ | oe icc we, а у RO Аға a а та 24.43 
determiners (in Masterscope) .................... 20.8 
DFNFLG (system variable/parameter) .............. 8.6; 5.6; 8.6; 14.38, 
"—— о ката = = о 22.33,40 
DEFEGRENCED AA |. ал свн EPIO ан ES 13.6 
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DIFFERENT EXPRESSION (printed by editor) ........ 9.55 
DIR (prog. asst. command) ....................... 21.11; 22.28 
DIRECTORIES (system variable/parameter) rm 17.21 
DIRECTORY[ FILEGROUP ; COMMANDS; DEFAULTEXT ; 

DEFAULTVERS;LISPXPRNTFLG] .............. 21.10 
disabling CLISP operators sererai vri I me EA 23.59 
DESMISSENMJ жа ъъ» вика eee водите пори Sor Es Paw died 
DISPLAYTERMFLG (system variable/parameter) ...... 21.15 
DISPLAYTERMP[] ............. er eee PTT 21.16 
DLAMBDA (in Decl package) Vp сен dor TEE EE 24,55,54 
DMPHASH[ARRAYNAME1;...;ARRAYNAMEn] NL* .......... 7.5 
DO (clisp iterative statement operator) ......... 23.12 
DO (edit. command] sariketa ee oes dea e dos x за ыза 9.52; 22.45 
СОВЕ | шеки au rus UA RE ERA балы endi a eaters Ба 14.18 
DOCOLLECT[ITEM; LST] . ive Ree ER во ВОЗИ ЗН а оа 6.3 
DOCOPY- (DECLARES ‘OPClON): оо бк T3 9 кни 14.59 
DOEVAL@COMPILE (DECLARE: option) .......... ELET 18.7; 14.59 
DOEVAL@LOAD (DECLARE: option) ................... 14.59 
DONTCOMPILEFNS (compiler variable/parameter) .... 18.6,8,21 
DONTCOPY (DECLARE: option) ...................... 18.7; 14.59 
DONTEVAL@COMPILE (DECLARE: option) .............. | 14.59 
DONTEVALGLOAD (DECLARE: option) ................. 14.59 
DONTMOVETOPFLG (dwim variable/parameter) ........ 17.7,9 
ПОС MOÓLULAETOB . ара ERR ренин RECHERCHER > ue 
DOTHESE (transor command) ....................... 24.29 
DOTHIS (transor command) ........................ 24.29 
dotted paik соба E Уа Ыб ей 5.1 
DPROG (in Decl package) 5... err kn 24.55,57 
DREMOVE[XSL] urbane ue а cared ee Oa we CE ER E E ал ЕЕ 6.3 
DREVERSETL] „лавра и wid bie аккыр ое P SE 6.4 
DRIBBLE[FILE;APPENDFLG; THAWEDFLG] ia aue ча idest речи 21.15 
DRIBBLEFILE[] SUBR .............................. 21.15 
рок (exec command) жга ааа вк еа ac EXE DCN 24.42 
DSKSTAT[DIR;PRINTIFOVER;PRINTSYS; PRINTDEL; 

PRINTOLD] ......... ОРУУ 24.43 
DSUBLISTALST: EXPRIFLG 4): оаа а а» 6.5 
DSUBST[NEW OLD EXPR] 5:5%5%5%5%555%55 RR “Ұбт 5,4,5 
DUMMY ERAMEP [POS |: зоон ақы алаша ње 12.7 
DUMP (transorset Command) ....................... 24.26 
DUMPDATABASE[FNLST] ............................. 20.20. 
DUMPDB FILET ела 555% Л е КЕ ак 24.32 
dumping circular 148438: на RAE ar ERE Y RR 14.22 
dumping unusual data structures ................. 14.22 
DUNPACK[X;SCRATCHLIST;FLG;RDTBL] ................. 10.3 
DW (edit command) ........................ селен 9.53; 17.18; 23.61 
DWIM[X] ise ва ка ee E ан 17.17,3 
Е ИРИТЕТ РРО РЕР 17.1-30; 2.6; 16,1 
DWIM interaction with user ..................... . 17.3 
DWIM variables ........... Q8 979-9 ЛЕЛЕ de VIN беден рабат Alako 
DWIM (prog. asst. command) ...................... 22.20-21 
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edit commands that test. s. 559 433 exer OK |. 9.43 

COVE HdCPOS 4554056 s duro із Оов Rs 9.45-46 
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EDIT (break command) ............................ 15.10,6,11-12 

EDIT (Masterscope command) ...................... 20.11 
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EDIT (transorset command) .........:............. 24.26 
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EDITCALLERS[ATOMS;FILES;COMS] ................... 9.60 
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EVAL (Masterscope template) ..................... 20.16 . 
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EVAEOTLEISPXIDO] озара лак Ұқ ын Кака 2.3; 5.7; 15.4 
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| EVALGLOAD (DECLARE: option) ..................... 14.59 
| | . EVALGLOADWHEN (DECLARE: option) ................. 14.59 
| Gvent 4007858. ханаан AIEO EORR 22.10-11 
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event specification сале виа eoo de TRACER RA кж» 22.10-12,16-17 
EVERY[EVERYX;EVERYFNA1;EVERYFN2] | ................. 5.11 
(EXAM . x) (edit command) ....................... 9.44 
exec package 94 3 визи зере ие Poe а кл ай 24.41-44 
EXEC (prog. asst. command) ...................... 22,24; 21.8; 22.28 
EXIT (transorset command) ....................... 24.26 
БАР (exec command) раса ка кан жк каты тек ке 24.42 
EXPANDMACRO[FORM;QUIETFLG] ....................... 18.11 
EXPLAINDELIMITER (askuser option) ............... 17.28 
EXPLAINSTRING (askuser option) .................. 17.27 
EXPR-(function type) 7040585 засы awe а 4.2; 8.3 
EXPR (property пате) „сеа или ко влакна sta 8.5,6; 9.58-60; 14.38, 
Мон ин =>" асынан | ~ 17.12-13; 18.5,14 
EXPRESSIONS (file package type) ................. 22.23 
EXPRPLEN | SUBR. ьан V RN өл а arena Pr 8.3,1-2,4 
OXDPS- aqu сл RUE 1/8 9 4 78 99 воо ORC RR wise = 4.1 
EXPR* (function Туре). uote] eX yy RES nm o 4.2; 8.3-4 
EXPT[MSN]. “асгана EY Жа Ее" 13.7 
EXPUNGEI DIR 95-5 а a ae Moa a d e . 24.43 
(EXTRACT 81 from . 02) (edit command) ........... 9.30 
(Р pattern М) (edit command) .................... 9.17 
(Е pattern n) (n a number, edit command) ........ 9.17 
(Е pattern T) (edit command) .................... 9.17 
(Е pattern) (edit command) ...................... 9.18 
Е pattern (edit command) ........................ 9.17 
Е (edit command) омања и ee REA РР 9.17,4-5 
ДАП: event addross) аео и ривер d 22,10 
Е (response to compiler question) ............... 18.1-3 
гате: зыка IRA EIC EN ОҚЫС еле OR ба ааа 5.3 
FASSOC[KEY;ALST] .............. приети 5.13; 2.2 
Таз Symbolit dump оо е ACE жа» кке кета 14.49 
FAST (makefile option) а.о ees a ERN m aa 9 ras 14.64 
FASTYPEFLG (dwim variable/parameter) ............ 17.17 
FAULT IN EVAL (error message) ................... 16.6 
FAULTAPPLY[FAULTFN;FAULTARGS] ................... 16.1; 17.3,10,14; 18.17 
FAULTEVAEFFAULTAT,NES- 55542 A CER а RR un 16.1,6; 17.3,10,14 
ЕВО P а вон преварени 24.38 
FBOX (record declaration) ....................... 24.38 
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FDIFFERENCEEXTY T. зебра C oed ни RURAL CERE 13.5 
FETCH (Masterscope relation) .................... 20.5 
FETCH (Masterscope template) .................. .. 20.16 
FETCH (use in records in clisp) ................. 23.26 
FETCHFIELD[DESCRIPTOR;DATUM] ..................... 3.8 
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FFETCH (use in records in clisp) ................ 23.26 
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РОНБАТЕКР ХОТ SUBR ааа ае кобна н 13.5 
FI (exec command) ........... ое е асыла жз 24.42 
FIELDLOOK[FIELDNAME] ............................ 23.35 
FIELDS OF (Masterscope set specification) ....... 20.7 
FILDIR[FILEGROUP;FORMATFLG] ..................... 21.8 — 
filo attributes олз ое E wo Rond кка 14.4-5 
filé command 7151: scd зави DII ҰС Rt GN ee 14.56 
FILE DATA ERROR (error message) ................. 24.45 . 
CREO аре: тен пали ~ ТЫ ee ка 14.41-42 
Tile пате 55 23-3923 94 00:9 27 9 3 ABRIR век ен 14.2,3,6-7 
FILE NOT COMPATIBLE (error message) ............. 14.36 
FILE NOT FOUND (error message) .................. 16.7; 14.2-3,38 
FILE NOT OPEN (error message) ................... 16.6; 14.2,5; 21.11 
file package ...... See РАМЫ лана, ТАРЫ пл 14.54-81 
file package commands ........................... 14.56-61,73-75 
file package TUDCLTOnS. 422252555455 5554 S Ee dur es 14.64-69,75-76 
file раскаде typos . = амен еа ор CIL 14.55-56 ,61-62, 72-73 
TUE: DONTE, - уа EV Бан WII a S dE Ds 14.7-8 
FILE SYSTEM RESOURCES EXCEEDED (error message) .. 16.7; 14.3 
FILE WONT OPEN (error message) .................. 14.3 
FILE WON'T OPEN (error message) ................. 16.6; 14.1-2 
FILE (edita parameter) .......................... 24.13 
FILE <property name) eux a SERE AU ти и Ue e de exe 14.63-64 
FILECHANGES (property name) ..................... 14.63,64,77 
FILECOMST FILE; XT 5:65 “е ЫЗ d RE xeu 14.76 
fileCOMS (in file package) ...................... 14.39,54,63-65,76 
FILECOMSESIEFItECTYPESELG]: eR Olea se 14.76 
FIEECREATEDEXT NLE uda о шани Aarau кия Se cete ees 14.79,60; 18.5 
FILEDATE[FILE:CFEG] аана HR n 2214.79 
FILEDATES (property пате) ....................... 14.63,64,77,79 
FILEDEF {property пате ) „е тае айа кез жез 17.12,14 
FILEFNSLSTEFILET жшше аала cw eee ee erate are 14.76 
FILEGROUP (property name) ....................... 14.66 
FILELINELENGTH (file package variable/parameter).. 14.64,48 
FILELST (file package variable/parameter) ....... 14,63,66; 17.21 
FILEMAP DOES NOT AGREE WITH CONTENTS OF file-name RE 
(error messado). ееш аон ss 14,42 

ҒПЕМАР (property name) ................. РЕЧЕ 14.41 
FILENAMEFIELD[FILENAME;FIELDNAME] ............... 14.6 
FILEPKGCHANGES(N © оен ee V ваа ЕТ 14.67 
FILEPKGCOM[COMNAME ;PROP1;VAL1;...;PROPn;VALn] * . 14.73 — 
FILEPKGCOMS (file package command) .............. 14.658,60 
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